Kony Studio Integrated Development Environment (IDE) User Guide
Below you will find brief information for Kony Studio Release 5.0. This user guide provides an overview of Kony Studio, an integrated development environment (IDE) for rapid mobile application development. It details how to design forms, add widgets, configure properties, integrate backend services with Kony Platform, and test applications using various emulators. The document also covers scripting with Lua/JavaScript, debugging, and internationalization.
PDF
Document
Advertisement
Advertisement
Kony Studio User Guide Kony Platform Release 5.0 Document Relevance and Accuracy This document is considered relevant to the Release stated on this title page and the document version stated on the Revision History page. Remember to always view and download the latest document version relevant to the software release you are using. Third_Party_Licenses Kony Studio User Guide - 2.1 Third Party Licenses This section acknowledges the Third-party companies for the license of their products. The third-party license in this section is for the Code Assistance and Inline Debugger features of Kony Studio. License LuaEclipse is free software: it can be used for both academic and commercial purposes at absolutely no cost. There are no royalties or GNU-like "copyleft" restrictions. LuaEclipse qualifies as Open Source software. Its licenses are compatible with GPL. LuaEclipse is not in the public domain and the Kepler Project keep its copyright. The legal details are below. The spirit of the license is that you are free to use LuaEclipse for any purpose at no cost without having to ask us. The only requirement is that if you do use LuaEclipse, then you should give us credit by including the appropriate copyright notice somewhere in your product or its documentation. The LuaEclipse library is designed and implemented by the Kepler Project team. The implementation is not derived from licensed software. -------------------------- Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ---------------------------- Copyright © 2012 Kony, Inc. All rights reserved. Page 2 of 785 Kony Studio User Guide - 2.1 Copyright Copyright © 2012 Kony, Inc. All rights reserved. February, 2015 This document contains information proprietary to Kony, Inc., is bound by the Kony license agreements and may not be used except in the context of understanding the use and methods of Kony Inc, software without prior, express, written permission. Kony, Empowering Everywhere, Kony MobileFabric, Kony Modeler,and Kony Visualizer are trademarks of Kony, Inc. Microsoft, the Microsoft logo, Internet Explorer, Windows, and Windows Vista are registered trademarks of Microsoft Corporation. Apple, the Apple logo, iTunes, iPhone, iPad, OS X, Objective-C, Safari, and Xcode are registered trademarks of Apple, Inc. Google, the Google logo, Android, and the Android logo are registered trademarks of Google, Inc. Chrome is a trademark of Google, Inc. BlackBerry, PlayBook, Research in Motion, and RIM are registered trademarks of BlackBerry. All other terms, trademarks, or service marks mentioned in this document have been capitalized and are to be considered the property of their respective owners. Copyright © 2012 Kony, Inc. All rights reserved. Page 3 of 785 Kony Studio User Guide - 2.1 Revision_History Revision History Date Document Version 9/20/2012 1.0 11/8/2012 1.1 12/14/2012 1.2 1/11/2013 1.3 04/03/2013 1.4 04/30/2013 1.5 06/19/2013 1.6 08/07/2013 1.7 Description of Modifications/Release SAP, Siebel,Sharepoint and Mainframe services added. Desktop Web Platform and features added. Custom widget import enabled. FFI support for JS added. Changing the Development Language of the Project. JS Debugger content added in Inline Debugger. FFI for JavaScript added. Building the application sections updated for JavaScript. Code Assist available for JavaScript Projects as well. Build ear files for Mobile Web. Document Release for 5.0. Windows 8 and Desktop Web support added. Document Release for 5.0. Automatic Preview feature added. Publish feature available for desktop web. iOS 6 support added. Application settings applicable on all platforms. License information available within Studio. Document Release for 5.0. Automatically upgrade project, BB10 and IE9 support for SPA, Splash screen changes for Android. Windows Phone 8 supported.Custom font support for Desktop Web. Document Release for 5.0. Map V2 support. SOAP preversion plugins information added in FAQ. Document Release for 5.0. Sync Integration with IDE. Section added for Developing Offline services. Document Release for 5.0. Map v2 additions. Added content for new resource folder structure. Added or modified the following topics: l Kony Sync Server Planning Guidelines l Kony Sync Application Design Guidelines l Before Publishing Application l FAQs related to SPA l Deeplink Function Appservice Function The following topics are updated: l l 02/03/2014 1.8 l l Apple documentation link in Splash Screen topic. Note added in Splash Screen topic on Android and iOS image exception. Note added on Mobile Web condition in Creating an Application topic. Copyright © 2012 Kony, Inc. All rights reserved. Page 4 of 785 Kony Studio User Guide - 2.1 Revision_History Date Document Version Description of Modifications/Release The following topics are updated: 02/10/2014 1.9 l Note added on available Java Service datatypes. BlackBerry COD file path updated. The following topics are updated: l l 04/03/2014 02/11/2015 2.0 2.1 An option to allow or block Certificate is added in Android properties. l New Android properties option added. l GCM Customization procedure added. l Modified local.war location in Desktop Web topic A new note is added in Creating an application section. Copyright © 2012 Kony, Inc. All rights reserved. Page 5 of 785 Table of Contents Kony Studio User Guide - 2.1 Table of Contents 1. Preface 16 1.1 Scope 16 1.2 Intended Audience 16 1.3 Typographical Conventions 16 1.4 Reference Documents 17 1.5 Contact Us 17 2. Introduction 18 3. Getting Started 19 3.1 Workspace 19 3.2 Kony Perspective 22 3.3 Views 30 3.4 Emulators 63 4. Kony Studio Preferences 70 4.1 Launching Preferences Window 70 4.2 Configuring Kony Studio Preferences 70 5. Utility Functions 73 5.1 Edit All Properties 74 5.2 Platform Porting 75 5.3 Form Merge Tool 80 6. Moving between Releases 84 6.1 Important Considerations 84 6.2 Upgrading to a Newer Release 85 6.3 Migrating from Newer Release to Older Release 86 7. Working with Applications 87 7.1 Categories of Applications 88 Copyright © 2012 Kony, Inc. All rights reserved. Page 6 of 785 Table of Contents Kony Studio User Guide - 2.1 7.2 Developing Single Page Applications (SPA) 91 7.3 Porting Applications to SPA 95 7.4 Developing Mixed Mode Applications 98 7.5 Creating an Application 105 7.6 Adding Forms to an Application 108 7.7 Adding Popups to an Application 113 7.8 Adding Widgets to a Form 117 7.9 Configuring Widget Properties 118 7.10 Applying Grid Layout 119 7.11 Importing Custom Widgets 121 7.12 Comparing and Replacing Forms 134 7.13 Adding Application Menu 150 7.14 Working with Resources 154 7.15 Importing and Exporting 164 7.16 Importing 165 7.17 Adding Templates in an Application 169 7.18 Configuring Headers and Footers 176 7.19 Working with Skins 177 7.20 Replacing/Copying Margins and Paddings 215 7.21 Adding a Code Module to an Application 218 7.22 Forking Forms 225 7.23 Forking Headers and Footers 226 7.24 Configuring Widget Property Defaults 228 7.25 Configuring Project Properties 230 7.26 Using Code Assistance 270 7.27 Importing Existing Applications 275 Copyright © 2012 Kony, Inc. All rights reserved. Page 7 of 785 Table of Contents Kony Studio User Guide - 2.1 7.28 Exporting Existing Applications 277 7.29 AndroidManifest File 279 7.30 Windows Manifest File 285 8. Changing the Development Language of a Project 290 8.1 Converting a Lua project to JavaScript: 290 8.2 Converting a JavaScript project to Lua: 290 8.3 Important Considerations when converting a Lua Project to JavaScript: 291 8.4 Important Considerations when converting a JavaScript Project to Lua 295 9. Working with Windows Phone7 Sequences or Views 296 9.1 Defining a Pivot Sequence 296 9.2 Defining a Panorama Sequence 298 9.3 Using Sequences 300 9.4 Important Considerations 300 9.5 Limitations 300 10. Working with Quick Preview 301 10.1 Prerequisites 301 10.2 Platform Support 301 10.3 iPhone Configuration 302 10.4 Preview Form 302 10.5 Preview on Emulators 304 10.6 Refresh Emulators for Modifications 312 11. Working with Automatic Preview 316 11.1 Prerequisites 316 11.2 Platform Support 317 11.3 iPhone Configuration 317 11.4 Configuring Automatic Preview for a Form 317 Copyright © 2012 Kony, Inc. All rights reserved. Page 8 of 785 Table of Contents 11.5 Preview on Emulators 12. Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 320 326 12.1 Advantages/Limitations 326 12.2 Prerequisites/Assumptions 326 12.3 FFI Approach 327 12.4 Using FFI for JavaScript Projects 327 12.5 Using FFI for Lua Projects 342 12.6 Guidelines for Third-party Libraries 353 13. Working with Event Editor 363 13.1 Launching Event Editor 363 13.2 Global Variables and Data Store Keys 364 13.3 Action Sequences 367 13.4 Event Flow Editor 384 13.5 Working with Mapping Editor 393 13.6 Working with Expression Editor 402 14. Working with Services 406 14.1 Service Definition File 406 14.2 Service Definition Tool 407 14.3 Using the Services 408 14.4 Preprocessor and Postprocessor 408 14.5 Data Provider 410 14.6 Response Encoding Schemes 412 14.7 Input and Output Parameters 413 14.8 Creating a Web (SOAP)/Sharepoint Service 414 14.9 Creating an XML Service 435 14.10 Creating a Java Service 441 Copyright © 2012 Kony, Inc. All rights reserved. Page 9 of 785 Table of Contents Kony Studio User Guide - 2.1 14.11 Creating a JSON Service 446 14.12 Creating a Composite Service 454 14.13 Creating a SAP Service 458 14.14 Creating a Siebel Service 465 14.15 Creating a WebSphere MQ Service [Mainframe] 475 14.16 Creating a Looping Connector 481 14.17 Service Definition Template 482 14.18 Publishing Services 495 15. Developing Offline Applications 498 15.1 Prerequisites for Accessing Offline Data Sources 498 15.2 Introduction to Kony Sync 501 15.3 Creating a SkyMobile Datasource 502 15.4 Introduction to Sky Mobile 502 15.5 Viewing the Sky Data Explorer 503 15.6 Connecting to a Sky Server 504 15.7 Working with the Kony SyncConfiguration View 508 15.8 Using the Sky Objects in your Application 519 15.9 Creating an Database Datasource 521 15.10 Working with the Kony SyncConfiguration View 524 15.11 Using the Database Tables in your Application 538 15.12 Creating a WebService Datasource 539 15.13 Working with the Kony SyncConfiguration View 539 15.14 Using the WebServices in your Application 554 15.15 Generate Application Forms 554 15.16 Generating Offline Services 559 15.17 Configuring Interceptors 563 Copyright © 2012 Kony, Inc. All rights reserved. Page 10 of 785 Table of Contents Kony Studio User Guide - 2.1 15.18 Loading an Existing SyncConfiguration File 564 15.19 Kony Sync Server Planning Guidelines 565 15.20 Kony Sync Application Design Guidelines 572 16. Working with Scraper Tool 578 16.1 Use Case Scenarios 578 16.2 Prerequisites for Using Scraper Tool 579 16.3 Input Parameters 583 16.4 Output Parameters 591 16.5 How to Use the Scraper Tool 600 16.6 Create a Scraper Service 614 16.7 Testing Scraper Service 620 17. Internationalizing (i18n) Application Content 622 17.1 Resource Bundle 622 17.2 Implementing Internationalization 622 17.3 Configuring i18n Locales 622 17.4 Configuring Default Locale for the Application 627 17.5 Configuring Custom i18n Locales 627 17.6 Adding i18n Content to the Application 634 17.7 Configuring i18n Key Property for Widgets 637 17.8 Internationalizing Splash Screen and Application Name 638 17.9 Internationalizing UI Elements and Widget Properties 640 18. Checking APIs and Data Types 18.1 Limitations 19. Building the Application 643 643 644 19.1 Prerequisites 644 19.2 Build Process 644 Copyright © 2012 Kony, Inc. All rights reserved. Page 11 of 785 Table of Contents Kony Studio User Guide - 2.1 19.3 Build Procedure 645 19.4 Building Application for Tablet Channels 649 19.5 Building Application for Mobile Web 649 19.6 Building an Application for Desktop Web 650 19.7 Viewing an Application on Desktop Web 651 19.8 Windows 8 Tablet features 651 19.9 Building an Application for Windows 8 Tablets 652 19.10 Viewing an Application on Windows 8 Tablet 652 19.11 Windows 8 features 656 19.12 Viewing an Application on Windows Phone 8 656 19.13 Building Application for Windows Kiosk 658 19.14 Combining Mobile Web with Middleware Archive for Application servers (WebLogic or WebSphere) 659 19.15 Viewing an Application on Emulators 661 19.16 Viewing an Application on Mobile Web 666 19.17 Publishing the Application 667 20. Debugging Applications 669 20.1 Before you Begin 670 20.2 Setting Up a JavaScript Application for Debugging 670 20.3 Setting Up a Lua Application for Debugging 673 20.4 Debug Configurations for Lua 676 20.5 Working in the Kony Debug Perspective 678 20.6 Debugging Operations 683 20.7 Stepping Through an Application 686 20.8 Evaluating an Expression 687 20.9 Debugging an Application 687 20.10 Debugger Behavior while Debugging Mobile Web Applications 688 Copyright © 2012 Kony, Inc. All rights reserved. Page 12 of 785 Table of Contents 21. Using Command Line Build Kony Studio User Guide - 2.1 689 21.1 Prerequisites 689 21.2 Configuring Files 690 21.3 Advantages 692 21.4 Building Application 693 21.5 Summary of Steps 695 22. Appendix: About the Kony Studio License 696 23. Upgrade Kony Studio 698 23.1 Upgrade to latest version of Kony Studio 698 23.2 Troubleshoot error message 704 24. Revert to Previous Configuration 706 25. Appendix: Eclipse Proxy Settings 710 25.1 Proxy Entries 710 26. Appendix: Basic or NTLM Proxy Authentication Configuration 711 27. Appendix: Deeplink Function 713 27.1 Working of Deeplink Function 713 27.2 Scenarios 713 27.3 Implementation Details 714 27.4 Example 714 28. Appendix: Appservice Function 716 28.1 Working of AppService Function 716 28.2 Scenarios 716 28.3 Implementation Details 717 28.4 Example 717 29. Appendix: Generating and Configuring Map API Keys 29.1 Application Level Map Widget Key 720 720 Copyright © 2012 Kony, Inc. All rights reserved. Page 13 of 785 Table of Contents Kony Studio User Guide - 2.1 29.2 Google Map Key for Android 721 29.3 Bing Map Key for Windows 724 30. Appendix: Handling Form Factors for Different Platforms 726 30.1 Android Smartphone/Tablet Platform 726 30.2 Android and Blackberry Mobile Web/ SPA Platform 729 30.3 BlackBerry Platform 730 30.4 iPhone/iPad/iPod Platform 737 30.5 J2ME Platform 738 30.6 Windows Mobile 7 Platform 739 30.7 Palm Pre Platform 739 30.8 Symbian/MeeGo Platform 739 31. iPad Orientations 741 32. Frequently Asked Questions about iPad Orientation (FAQs) 743 33. Appendix: BlackBerry MDS 745 34. Appendix: Profiler 746 34.1 Profiler Setup for iOS 746 34.2 Profiler Setup for Android 750 34.3 Profiler Setup for BlackBerry 752 35. Appendix: Sample URL Provider for Service Definition 754 36. Appendix: Sample Skin.xml File 755 37. Appendix: GPS Functionality 758 37.1 Supported Platforms on Mobile Web 758 37.2 Process for Capturing Location Details 758 38. iWay Enterprise Connectors 760 39. Appendix: web.xml 761 40. Appendix: Integrated Help and Context Sensitive Help 770 Copyright © 2012 Kony, Inc. All rights reserved. Page 14 of 785 Table of Contents Kony Studio User Guide - 2.1 40.1 Integrated Kony Help 770 40.2 Context Sensitive Help 771 41. Appendix: Frequently Asked Questions 773 Copyright © 2012 Kony, Inc. All rights reserved. Page 15 of 785 Kony Studio User Guide - 2.1 Preface 1. Preface Kony Studio is an integrated development environment (IDE) for rapid development and deployment of mobile applications. Kony Studio is provided as a plug-in to Eclipse, an open-source environment. The IDE offers you an easy to learn and use visual development environment to design and develop the mobile applications. The primary element of Kony Studio is a visual developer panel that is used to design the application forms in a device independent wire-frame format. All the Kony supported devices, development languages, and browsers are listed at, Supported Devices and Browsers. 1.1 Scope This document explains the terms and concepts in the IDE and also provides procedural information to perform various tasks in the IDE. 1.2 Intended Audience This document is targeted at developers who will use the IDE to write and develop applications. 1.3 Typographical Conventions The following are the typographical conventions used throughout the document: Click Here Conventions Monospace Italic Bold Explanation n User input text, system prompts and responses n File Path n Commands n Program Code n n File Names. Emphasis n Names of Books and Documents n n New Terminology. Windows n Menus n Buttons n Icons n Fields n Tabs n Folders. Copyright © 2012 Kony, Inc. All rights reserved. Page 16 of 785 Kony Studio User Guide - 2.1 Preface Conventions URL Note: Important! Explanation Active link to a URL. Provides helpful hints or additional information. Highlights actions or information that might cause problems to systems or data. 1.4 Reference Documents 1. Kony Server Installation Guides 2. Kony Studio Installation Guide 3. Kony Widget User Guide 4. Kony API Reference Guide 1.5 Contact Us We welcome your feedback on our documentation. Write to us at [email protected]. For technical questions, suggestions, comments, or to report problems on Kony's product line, contact [email protected]. Copyright © 2012 Kony, Inc. All rights reserved. Page 17 of 785 Introduction Kony Studio User Guide - 2.1 2. Introduction The IDE provides an extensive and powerful library of pre-built widgets that you can use to handle most common application requirements. The Kony Client library has widgets that cover the following: l simple user input elements l text and graphical display elements l widgets that can access device functions such as camera and location data l complex widgets (for example, Advertisement widget) with configurable behavior. You can also choose to render widgets only on specific devices, to obtain customized interfaces and skins, which optimize the capabilities and look and feel of each device operating system. A resource model allows for static resources such as images, videos, and sounds. Kony Client libraries also include support for platform specific properties. The platform specific properties allows the application to have the native look and feel on the respective platforms. The IDE enables the development of common functionality across all platforms, but also offers the ability for you to customize device specific properties that are available only on certain platforms. Using this capability, you can maintain one code base, but still deliver an optimized application experience for a specific device by configuring additional device or platform properties provided by the platform. Back-end data integration is also simplified using the Kony Platform. You do not need to move or copy existing data in order to create a mobile application. Instead, Kony Platform is able to communicate directly and securely with a client's current data system, writing this data connection once and then applying it to all devices. Kony Studio supports multiple classes of markup generation based on device capabilities, and devices may receive WML, cHTML or a combination of XHTML, CSS and JavaScript based on the capabilities detected at run-time. Kony Studio also enables rapid testing of these applications in device emulators from all major manufacturers. These emulators are available in emulator view in the IDE. Direct integration with the data services supported by the server, is provided through a simple mapping interface that enables complete transactional applications to be built without any coding on your part. In addition, a simple but powerful scripting environment allows you to implement complex user interface or application functionality. Copyright © 2012 Kony, Inc. All rights reserved. Page 18 of 785 Getting Started Kony Studio User Guide - 2.1 3. Getting Started You must install Eclipse IDE for Java EE Developers versions, 3.4.2, 3.5.x, 3.6.x.Recommended - Eclipse 3.6.2 - Helios 32 Bit as a prerequisite on your local computer to understand the various concepts and to perform various operations listed in this document. For more information about installing Eclipse, see Kony Studio Installation Guide. The folder containing the eclipse installable should not have any space in its name. To get started with creating or developing applications in the IDE, you should be familiar with the following concepts/terminology: l Workspace l Kony Perspective l Views l Applications l Emulators. 3.1 Workspace Workspace is a folder on the hard drive, which is a central repository of all application files. The applications you create in the IDE are saved in the workspace. A workspace can have any number of applications. The basic purpose of workspaces is to organize the applications you develop. If you have multiple workspaces, you can logically organize the applications into different workspaces. This organization makes it easy for you to search the applications when needed. When you launch Eclipse for the first time, the workspace is automatically created in the C drive as C:\workspace. This is the default workspace. Note: The default workspace is created in C drive even if you install Eclipse in other drive, for example D: or E. The IDE provides you with the option to create your own workspace. For more information about creating a workspace, see Creating a Workspace. You can also switch between workspaces depending on the application you are accessing. For more information about switching from one workspace to another, see Switching Workspaces. Every application that is available in the current workspace or that has been imported into the current workspace is visible under the Applications view and Navigator view. If you have imported an application into the workspace, it may not be automatically visible. You must right-click and select Refresh All in the Applications view area or select Refresh in the Navigator view area to update the view with the list of applications. Note: If the application is not available under the Applications view or Navigator view, you cannot work on it. Copyright © 2012 Kony, Inc. All rights reserved. Page 19 of 785 Getting Started Kony Studio User Guide - 2.1 3.1.1 Creating a Workspace If you have multiple workspaces, you can logically organize the applications into different workspaces. Though there is a default workspace in the C drive, you can create a workspace and map the development environment to the newly created workspace. Now this newly created workspace becomes the current workspace. All the applications you create from now on are created in the current workspace. To create a workspace, follow these steps: 1. Create any folder, which you want to use as workspace on any drive. For example, D:\MyWorkspace. Note: We recommend to name the workspace in Camel Case (capitalize the first letter of every word). Important: Do not use any spaces or special characters while naming the workspace. 2. Launch Eclipse. 3. Select File -> Switch Workspace. Note: If you have already switched your workspace previously, the previous workspaces will be available for selection in the Switch Workspace menu. 4. Select Other if you want to create a new workspace. 5. Workspace Launcher dialog appears as shown below. This window will allow you to browse for or manually enter a new workspace location. 6. Select the workspace from the combo box or browse for the workspace folder. 7. Expand Copy Settings as shown in the above window. 8. Select Workbench Layout when you want the opened views, their size, and selected perspectives to be copied to the switched workspace. Copyright © 2012 Kony, Inc. All rights reserved. Page 20 of 785 Getting Started Kony Studio User Guide - 2.1 9. Select Working Sets to copy the working set settings to the new workspace. Note: Working sets enable you to group elements for display in views. 10. Click OK. The new workspace is created. Note: Eclipse restarts and opens in the newly created workspace. 3.1.2 Switching Workspaces When you develop applications, you can choose to organize the applications in different workspaces by creating multiple workspaces rather than maintaining them in a single workspace. If you create multiple workspaces, you must switch from one workspace to another to work on different applications. To switch from one workspace to another, follow these steps: 1. Select File -> Switch Workspace -> Other. Note: If you have already switched your workspace previously, the previous workspaces will be available for selection in the Switch Workspace menu. 2. Select Other if you want to select some other workspace. Workspace Launcher window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 21 of 785 Getting Started Kony Studio User Guide - 2.1 This window will allow you to browse for or manually enter a new workspace location. 3. Select the workspace from the combo box or browse for the workspace folder. 4. Expand Copy Settings as shown in the above window. 5. Select Workbench Layout when you want the opened views, their size, and selected perspectives to be copied to the switched workspace. 6. Select Working Sets to copy the working set settings to the new workspace. Note: Working sets enable you to group elements for display in views. 7. Click OK. Note: Eclipse restarts and opens in the newly selected workspace. 3.2 Kony Perspective A perspective defines the initial set and layout of views in Eclipse. Kony Perspective is a customized IDE to develop applications that are specific to Kony Platform. You can directly create a Kony application from the menu in Kony Perspective. All the menu items that are available in the default perspective are not available in the Kony Perspective. Only menu items that are relevant to Kony applications appear in the menus. Kony Perspective also has a few toolbar items specific to it. When you open Kony Perspective in Eclipse, you will see the following views: l Applications View l Navigator View l Form Designer l Properties View l Services View l Outline View l Console View l Progress View Copyright © 2012 Kony, Inc. All rights reserved. Page 22 of 785 Getting Started l Skins View l Emulators View. Kony Studio User Guide - 2.1 For more information about opening Kony Perspective, see Launching the Kony Studio. Note: If you are not able to see any of the views listed above, reset the perspective. The Kony Perspective in Eclipse is as shown below (default view): 3.2.1 Launching the Kony Perspective You should launch Eclipse first to open the Kony Perspective. To launch Eclipse, follow these steps: 1. Navigate to the Eclipse installation folder. For example, C:\eclipse . 2. Open the eclipse folder. 3. Double-click eclipse.exe file to launch Eclipse. For more information about Launching Eclipse, see Kony Studio Installation Guide. To launch Kony Perspective, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 23 of 785 Getting Started Kony Studio User Guide - 2.1 1. Launch Eclipse. Eclipse opens with the following default view with Java perspective displayed on the top-right corner. 2. Select Window -> Open Perspective -> Other. Open Perspective window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 24 of 785 Getting Started Kony Studio User Guide - 2.1 3. Select Kony and click OK. 4. Kony Studio launches with Kony perspective as shown in the screen below: 3.2.1.1 Save Perspective You may want to see only certain views, views in specific locations and sizes in a perspective each time you open Eclipse. In such cases, you need to save the perspective. To save perspective, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 25 of 785 Getting Started Kony Studio User Guide - 2.1 1. Make the changes you need in the perspective. Changes can be anything like opening new views, moving views around the window, changing the size of the views, or closing existing views. 2. Select Window -> Save Perspective As. 3. Enter a name for the perspective under Name field. 4. Click OK. The perspective is saved with the name you have specified. The next time when you open this perspective, the view you have saved will be retrieved and displayed on the screen. 3.2.1.2 Reset Perspective While working with the applications in the IDE, if you have closed some of the Views and want to view them again, you must reset the current perspective to view the windows or Views that have been closed earlier. If you Reset a perspective, you are presented with the default view of the Kony Perspective. To reset the perspective, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 26 of 785 Getting Started l Kony Studio User Guide - 2.1 Select Window -> Reset Perspective. 3.2.1.3 Close Perspective If you have opened too many perspectives, navigating from one perspective to another may become cumbersome. You may want to close the perspective you are currently working in or any other perspective that you may have opened earlier. In such a case, use the Close Perspective menu item. To close a perspective, follow these steps: 1. Select Window -> Close Perspective. This closes the perspective you are currently working in. Copyright © 2012 Kony, Inc. All rights reserved. Page 27 of 785 Kony Studio User Guide - 2.1 Getting Started 2. Select Window -> Close All Perspectives. This closes all the perspectives in Eclipse. When you close all the perspectives in Eclipse, you see a window as shown below: 3. Click to open a perspective in Eclipse. 3.2.2 Menus Menus provide a convenient access to various operations such as saving or opening a file, quitting a program, or manipulating data. Copyright © 2012 Kony, Inc. All rights reserved. Page 28 of 785 Getting Started Kony Studio User Guide - 2.1 Menu along with menu items is as shown below: Note: Some of the menu items that appear in the menus are specific to Kony Platform. For example, Kony Application in File -> New. Context Menu is as shown below: The context menu is also specific to Kony Platform. When you install Kony Studio, a menu item called Kony Dev Studio is available under Window -> Preferences. This menu item helps you configure various options for the Kony Studio. Copyright © 2012 Kony, Inc. All rights reserved. Page 29 of 785 Getting Started Kony Studio User Guide - 2.1 Note: Kony Dev Studio option in the left pane of the above window appears only when you have installed Kony Studio. 3.2.3 Toolbars Kony perspective has the following toolbar items on the toolbar in addition to the normal toolbar in Eclipse: In this toolbar: l l l is the Delete icon. This icon is to delete the selected widget (form or any widget). is the Preview icon. This icon is to preview the selected form. is the Build icon. This icon is to build the developed application. 3.3 Views A view is a small visual component within Kony Studio to navigate through resources, or to display properties for building or editing. All the views you see in Kony Perspective are specific to Kony Platform. The same views may have different names and look-and-feel in other Perspectives. Kony Studio has the following views: l Applications l Navigator l Form Designer Copyright © 2012 Kony, Inc. All rights reserved. Page 30 of 785 Getting Started l Properties l Services l Outline l Console l Progress l Skins l Emulators. l Video l Enterprise Explorer Kony Studio User Guide - 2.1 3.3.1 Applications View Applications are designed to help you perform singular or multiple tasks. Applications view is the starting point for creating an application. Applications view lists all the applications available in current workspace. Applications view is as shown below: 3.3.1.1 Build Artifacts The Applications View displays a list of all the platform plug-ins installed in Eclipse. Click Platform Plugin Details window appears. . Kony Copyright © 2012 Kony, Inc. All rights reserved. Page 31 of 785 Kony Studio User Guide - 2.1 Getting Started 3.3.1.2 Build Options Click to perform an incremental build on the application. Click the drop-down next to the build icon to see the other options for building an application. For more information on various build options refer, Building Applications 3.3.1.3 Open Folders Click to open the location of project in the workspace. Click the drop-down next to this icon and select any of the following options to open the corresponding folders: Folder Resources folder Build Folder Webapps Native folder Webapps Mobile Web folder Shortcut Key Ctrl+Alt+O Ctrl+Alt+T Ctrl+Alt+W,R Ctrl+Alt+W,T 3.3.1.4 Copying contents within and across applications You can copy the following contents of a folder of an application within an application or across applications: l l l Forms: You can copy or drag a form within the same application or across applications. When you do so, all the platform specific properties and the defined common properties and events are copied as well. Modules: You can copy a module of one application to the module of another application. Resources: You can copy the images present in the resources subfolder to other subfolders within the resources folder. You can also copy the subfolders across applications. Copyright © 2012 Kony, Inc. All rights reserved. Page 32 of 785 Getting Started l Kony Studio User Guide - 2.1 Services: You can copy the service definition files across applications. For example, an xml service defined for an application can be copied to an xml service of another application. When you drag and drop a service only the definition file is copied and its subsequent libraries are not copied. If the target to where you are copying the content to already has a resource/form/module/service with the same name, the following options appear: l Rename: Renames the content you are trying to copy to the target folder. l Overwrite: Overwrites the changes of the target with the new content. l l l Merge:Allows you to merge the changes of the content in the target folder with the content you are trying to copy by using the Form Merge Tool. Ignore: Retains the original content of the target and ignores the changes in the content you are trying to copy. Cancel: Cancels the copy operation. 3.3.2 Navigator View Navigator view displays a hierarchical representation of the current workspace and all applications in it. This view facilitates you to import existing projects from other repositories or workspaces. The navigator view is as shown below: 3.3.3 Form Designer The central area in the IDE where the forms and code modules are opened is known as Form Designer. The Form Designer also consists of a Widget Palette. The Widget Palette is available only when a form/popup is open. Any form/popup or code module that you select opens in the Form Designer. You can do the following on a Form Designer: l Open and view forms l Add widgets to a form l Edit the widget's properties by selecting the widget l Adjust the placement and alignment of the widget Copyright © 2012 Kony, Inc. All rights reserved. Page 33 of 785 Getting Started l Open and edit a code module l Open and edit services or the XML files l Open and edit the service definition XML files. l Double-click a widget and edit its properties. l Apply Grid Layout. Kony Studio User Guide - 2.1 The Form Designer is as shown below: The Preview button to the right of the form in the Form Designer allows you to preview the selected form on the emulator. Note: You can see the Widget Palette in the Form Designer only when you open one or more forms. The widget palette can be in collapsed or expanded form. For more information, see Widget Palette. Copyright © 2012 Kony, Inc. All rights reserved. Page 34 of 785 Getting Started Kony Studio User Guide - 2.1 You can open any form/popup, service, or code module in the Form Designer. If there are many forms or windows open in the Form Designer, click the icon on the title bar of the Form Designer to select the required form or window from the drop-down list. Note: If you double-click the form or service that is already open in the Form Designer, that form or window is focused in the Form Designer. Using the Navigation Pane as indicated in the figure, you can navigate to all the forms, properties files, build files, xml files etc present in a particular workspace. 3.3.3.1 Code Modules Kony Platform uses Lua/JavaScript (an open source scripting language) for scripting. Lua/JavaScript provides a powerful scripting environment with a small memory footprint that is well-suited for mobile environments. Kony has implemented optimized Lua Virtual Machines (VM) for each mobile platform/OS (except for the iPhone). A code module can contain one or more functions and these functions can be used in various areas of the application as required. These code modules organize the defined functions logically. The IDE provides a Lua syntax-aware code editor that is used to develop the required application client logic. The code module view is as shown below: To go to Code view, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 35 of 785 Getting Started Kony Studio User Guide - 2.1 1. Go to Applications view. 2. Select an application and expand it. 3. Expand modules. 4. Double-click any module in the lua/ js folder. The Lua/JavaScript module opens in the Script Editor. The area where the code module opens in the Form Designer is known as the Code view. 3.3.3.2 Widget Palette A software library containing a collection of widgets that collaborate in designing or development of applications is known as a Palette. Note: All the widgets are arranged in alphabetical order. The following is a snapshot of Palette in expanded form: By default, the palette is collapsed. You can click the icon on the top-right corner of the palette to view the palette in an expanded form. When the palette is expanded, click the icon on the top-right corner of the palette to collapse it. Copyright © 2012 Kony, Inc. All rights reserved. Page 36 of 785 Getting Started Kony Studio User Guide - 2.1 You can pin open the palette to see the Container Widgets, Basic Widgets, and Advanced Widgets in an expanded form. Click the icon against each category of widgets to pin open that category. When you pin open a category, it remains open until you click the icon again. 3.3.3.3 Widget Classification The following is a structural classification of the widgets: 1. Composite Widgets: Form and Popup 2. Command Input Widgets: Button, MenuItem 3. Data Input and Output Widgets: CheckBox, ComboBox, Link, ListBox, RadioButtonGroup, RichText, TextArea, TextBox, and Switch. 4. Informational Widgets: Calendar, Hz Image Strip, Image, Image Gallery, Label, Line, and Slider. 5. Advanced Widgets: Browser, Camera, Hz Image Strip, Image Gallery, Map, Phone, PickerView, Segment, and Switch. Widgets are categorized (based on the behavior and characteristics of the widgets) as follows: l Container Widgets l Basic Widgets l Advanced Widgets. The following sections describe the behavioral classification of the widgets: Container Widgets These are a set of widgets that hold basic and advanced widgets within them. The container widgets trigger events upon receiving user actions. The following is a list of Container Widgets: l Form l HBox Note: An HBox can be placed only within a Form, VBox, TabPane, a Segment, or a ScrollBox(only if the orientation is set as vertical). l VBox Note: A VBox can be placed only within an HBox. l TabPane l Tab l Popup. Note: Among all the widgets, Form is the starting point to hold any type of widget. A Form can hold other container widgets, basic widgets, and advanced widgets. A Form can never hold another form. Copyright © 2012 Kony, Inc. All rights reserved. Page 37 of 785 Getting Started Kony Studio User Guide - 2.1 Basic Widgets Some of the basic widgets trigger events upon receiving user input or based on user actions. The following is a list of Basic Widgets: l Button l Calendar l CheckBoxGroup l ComboBox l DataGrid l Image l Label l Line l Link l ListBox l MenuItem l RadioButtonGroup l RichText l Slider l TextArea l TextBox. Note: All the basic widgets can be placed only on Container widgets like a Form, HBox VBox, or a Popup. Advanced Widgets The following is a list of Advanced Widgets: l Browser l Camera l Hz Image Strip l Image Gallery l Map l Phone l PickerView l Segment l Switch 3.3.3.4 Palette Layout Copyright © 2012 Kony, Inc. All rights reserved. Page 38 of 785 Getting Started Kony Studio User Guide - 2.1 The Widget Palette can be laid out as per your requirement. The Palette provides you the option to view the widgets in the following views: l l l Columns Displays all the widgets column-wise as shown below: List Displays a list of all the widgets in the Palette as shown below: Icons Only Displays a list of icons as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 39 of 785 Getting Started l Kony Studio User Guide - 2.1 Details Displays a list of all the widgets along with the details as shown below: To launch the Palette in different Views, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 40 of 785 Getting Started Kony Studio User Guide - 2.1 1. Open the Widget Palette. 2. Right-click any of the widget categories and select Layout. 3. Select the required layout. The widgets in the Palette appear in the selected view. 3.3.3.5 Palette Settings You can set the font of the widgets in the Palette and also the view in which the widgets should be displayed within the Settings of the Palette. To configure the palette settings, follow these steps: 1. Open the Widget Palette. 2. Right-click any of the widget categories and select Settings. Copyright © 2012 Kony, Inc. All rights reserved. Page 41 of 785 Getting Started Kony Studio User Guide - 2.1 3. Click Change to open the Font window. Select the required font. 4. Select the required Layout. For more information, see the section Palette Layout. 5. Select the required Drawer options. The Drawer options affect the pinning of the widget palette. l l l Always close when opening another drawer - closes the other categories of the widgets when another category is opened. Close automatically when there is not enough room - closes the other categories of the widgets when there is not enough space on the Widget Palette. Never close - all the categories in the widget palette always remain open. 3.3.3.6 Editing Widget Properties Kony Platform allows you to edit and filter the widget properties of widgets placed in a form. To launch the Edit Properties dialog, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 42 of 785 Getting Started Kony Studio User Guide - 2.1 1. Open a form with widgets in it. 2. Double-click a widget. The Properties dialog appears. 3. You can edit the properties of the widget in a form by clicking in the value column and selecting an appropriate value. 4. You can also filter widgets using the filter area provided. The Filter Area enables you to filter the following: l l l l Widget: Enables you to view a certain widget in the form. Only the widget entered in the Widget field is displayed. Category: Enables you to view the categories of widgets. Only the category entered is displayed. The widgets properties are categorized by their General properties, Appearance, Events, and the Platform names. Property: Enables you to view the properties of widgets. Only the property entered is displayed. The widget properties are the common properties and the platform specific properties of a widget. Whole Word: Enables you to search the widget or property by the entire keyword entered in the Widget/Category/Property field. Copyright © 2012 Kony, Inc. All rights reserved. Page 43 of 785 Kony Studio User Guide - 2.1 Getting Started 3.3.4 Properties View Each widget has a set of associated properties. Each property represents a specific behavior of the widget. You can set properties for a widget using the Properties view. For more information about working with widgets and setting their properties, see Kony Widget User Guide. The Properties window has two views. You can view the properties either grouped into categories or all the properties listed together. Click the button to toggle between two views of the Properties window. The Properties window is as shown below: Properties in categorized view Properties in a list view 3.3.4.1 Common Properties Widgets have common properties that control their appearance and functionality. Some of the common properties are ID, Visible, Render, Title, Title i18n Key, Padding (%), Margin (%), Location, Size, and so on. These properties are common across all the widgets and specify a defined behavior. The following screen shows the area of the Properties window where you set the common attributes: Copyright © 2012 Kony, Inc. All rights reserved. Page 44 of 785 Getting Started Kony Studio User Guide - 2.1 The following screen shows the area of the Properties window where the events of a widget are listed: Each event has an action sequence associated with it that gets executed. 3.3.4.2 Platform Specific Properties Platform specific properties, as the name denotes, are specific to the platform on which they are set. These properties do not affect other platforms. Setting the platform specific properties for a widget differentiates the behavior of that widget from other platforms. For more information about platform specific properties, see Kony Widget User Guide. The following screen shows the area on Properties window where you can set platform specific properties: Copyright © 2012 Kony, Inc. All rights reserved. Page 45 of 785 Getting Started Kony Studio User Guide - 2.1 3.3.4.3 Widget Renderer Render is a common property of any widget that defines if the widget needs to be made available on a specific platform. If the Render property is set to true, then that widget is available on a specific platform. For more information about rendering a widget on specific platforms, see Kony Widget User Guide. The following screen shows the area on the Properties window where you can set the Render property: When you click on the Render property, the following screen appears where you set values for different platforms: Copyright © 2012 Kony, Inc. All rights reserved. Page 46 of 785 Getting Started Kony Studio User Guide - 2.1 For examples and different scenarios of rendering a widget on specific platforms, see Kony Widget User Guide. 3.3.5 Services View Services View displays the list of all the services that are associated with the application. All the services that are a part of the service definition file are populated here in this view. The services are categorized under various heads like: l Web Services - SOAP Services l XML Services l Java Services l JSON Services l Composite Services l Looping Services l SAP Service l Siebel Service l Mainframe Service l Define Service Template When you expand any category of services, you can see the list of all services under that category. When you expand any service in turn, you can see the list of input and output parameters. Note: The number of services of a specific category is also listed against each category. The Services View is very helpful for the developers to see the entire list of services defined within an application at one place. The Services View also shows the following apart from the services within the application: Copyright © 2012 Kony, Inc. All rights reserved. Page 47 of 785 Getting Started Kony Studio User Guide - 2.1 l Global Variables defined to be accessed across services and the application l Data Store Keys l Global Event Sequences. The Services view is as shown below: 3.3.6 Outline View Outline View provides a structured view of the form/popup components and each selected component directs to property window. The Outline View has two different views: l Tree View l Preview. The Tree View is the default view of the Outline View. The Tree View is as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 48 of 785 Getting Started Kony Studio User Guide - 2.1 The Outline View window shows a miniature preview of the form/popup that is open in the Form Designer. If the form/popup spans beyond the viewable area of the Form Designer, the area of the form/popup that is visible in the viewable area is highlighted in Blue color in the Outline View. If you resize the Outline View window, the miniature preview in that window is adjusted automatically according to the width of the Outline View. When you click anywhere on the miniature preview, that part of the form/popup is visible in the Viewable area of the Form Designer. The Preview is as shown below: Note: The Tree View shows the hierarchy of the form/popup along with the widgets contained in it. The Preview shows the layout of widgets on the form/popup. Copyright © 2012 Kony, Inc. All rights reserved. Page 49 of 785 Getting Started Kony Studio User Guide - 2.1 3.3.7 Console View The term console refers to a terminal attached to Kony Studio. This console displays the status of the application during compilation process. Console view is as shown below: 3.3.8 Progress View Progress View is tabbed to the Console view. The Progress view, as the name suggests, displays the progress of the various operations that can be performed on an application. The operations can be: l Building the application l Previewing the application l System operations. The Progress View is as shown below: Click to cancel any operation that is running in the Progress View. Copyright © 2012 Kony, Inc. All rights reserved. Page 50 of 785 Getting Started Kony Studio User Guide - 2.1 3.3.9 Skins View The skin attributes capture the look and feel of every widget. A widget can have a different look and feel by applying a different skin to it. Skins are specific to widgets and also specific to Platforms. Skins view displays a list of all widgets along with their associated skins. Skins view is as shown below: You can perform the following actions in the Skin window using the toolbar: l Refresh - refreshes the skin window l Search - opens a search window where you can search for skins. l Import - provides you with the ability to import existing skins into the IDE in XML format. l Export - provides you the ability to export the selected skins as skin.xml to the selected folder. l Clone - provides you the ability to clone all existing skins to selected platforms. For more information, see Cloning Skins. 3.3.10 Themes View Kony Studio provides a default theme that has a set of skins defined for all the widgets within an application. The skins in this theme can be applied to widgets to get a different look and feel for the widgets. The Themes View is embedded in the Skins View. A drop-down list indicating the current theme appears in the Skins View. you can see theme to which all the skins are associated with. Copyright © 2012 Kony, Inc. All rights reserved. Page 51 of 785 Getting Started Kony Studio User Guide - 2.1 Kony Studio also provides you to create themes and associate skins with them. When you create a theme, it is created using the default theme as the base. All the skins available in the default theme are copied to the created theme. The IDE allows you to add, modify, rename, copy, fork, clone, and delete skins within a theme. Kony Platform provides a set of APIs that allow you to perform different actions with themes. For more information on themes, refer Themes. 3.3.11 Emulators View This view displays a list of virtual mobile devices available for testing the application. For more information about emulators, see Emulators. Copyright © 2012 Kony, Inc. All rights reserved. Page 52 of 785 Kony Studio User Guide - 2.1 Getting Started The Emulators view is as shown below: Android emulators are classified as: l Mobile l Tablet l Devices - Right-click Devices and select Get Connected Devices via USB. This option allows you to launch any of the listed devices to install the application. 3.3.12 Scraper View The Scraper allows you to test your scraper services right within the IDE. The DSL integration feature of Kony Studio helps you to launch this view. To Integrate the DSL Files with Kony Studio, follow these steps: Eclipse 3.4 l Download the kony.dsl and kony.dsl.editor plug-ins available in the kony_ dsleditor_plugin to the plugins or dropins folder of Eclipse. Eclipse 3.5 and above l Download the kony.dsl and kony.dsl.ui plug-ins available in the kony_ dsleditor_3.6plus_plugin to the plugins or dropins folder of Eclipse. l Download the external-jars.gz file from respective plugin/plugins folder. l Extract it into the Eclipse plugins or dropins folder. Copyright © 2012 Kony, Inc. All rights reserved. Page 53 of 785 Getting Started Kony Studio User Guide - 2.1 Opening the Scraper View Navigate to Window -> Show View -> Other -> Kony Studio -> Scraper Input. 3.3.13 History View The History View enables you to compare forms versions saved in the Local History or in SVN using the Tree View or Graphical View. History view displays a list of all the previously saved forms. History view is as shown below: You can perform the following actions in the History window using the toolbar: l Refresh - refreshes the History window l Link with Editor and Selection: - displays the history of the form currently active in the Editor Pane. l Pin this History View - pins the History View besides the Emulator View. l Switch History - enables you to switch among the histories of forms that are open in the Editor Pane. l Group Revisions by Date - enables you to group the prior saved versions of a form by date. l Compare Mode - enables you to compare forms using the Tree View or the Graphical View. For more information see Comparing Forms. Opening the Profiler View 1. Go to Applications view. 2. Select a form. Copyright © 2012 Kony, Inc. All rights reserved. Page 54 of 785 Getting Started Kony Studio User Guide - 2.1 3. Expand forms. 4. To compare a form with a prior saved version, right-click on a form and select Compare With. 1. Click Local History. The History View appears besides the Emulator View. Copyright © 2012 Kony, Inc. All rights reserved. Page 55 of 785 Getting Started Kony Studio User Guide - 2.1 3.3.14 Profiler View The Profiler provides the performance analysis of an application which is developed using the Kony Studio. It recognizes all Lua method calls and the Kony API calls as well. For more information on Profiler, refer Profiler Opening the Profiler View 1. Within Kony Studio, navigate to Window> Show View > Other. The Show View dialog appears. 2. Type Profiler in the textfield provided. 3. Select Profiler and click OK. The Profiler for Android appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 56 of 785 Getting Started Kony Studio User Guide - 2.1 For more information on using the Profiler View, refer Appendix: Profiler. 3.3.15 Video View The Video View enables you to view the videos (media in MP4 format) within Kony Studio IDE. You can get the Video View feature only when you install/copy the Video Plugin into the dropins folder of your Eclipse. Kony provides the video plug-ins in two formats, with the same name: l The light weight video plug-in (with links to the videos and no videos within the plug-in itself) and l The heavy weight video plug-in (with all the training/feature videos pre-packaged into it). You have a choice to download any one of it and install it in Kony Studio. If you download the heavy weight plug-in, you can click on the required video from the playlist or the library and instantly watch the video in the video view. Light-weight video plugin will not download the video when you use the default play option or double-click the video, it will stream the video from the web. If the user wants to download video he has to select the Download And Play option to actually download the video and use it later. Both the options will prompt the user with credentials for Developer Portal. Opening the Video View 1. Within Kony Studio, navigate to Window> Show View > Other. The Show View dialog appears. 2. Type Video in the textfield provided. Copyright © 2012 Kony, Inc. All rights reserved. Page 57 of 785 Kony Studio User Guide - 2.1 Getting Started 3. Select Video and click OK. The Video view appears. Using the Video View 1. Click , to open an external url within Kony Studio. The Video plays within the Player Tab 2. Click , to view the video in full screen. 1. You can perform the following operations using the Playlist tab: i. Under the Playlist tab, you can view the videos which are a part of the playlist. ii. Using the icon, you can add a video to the playlist. iii. Using the icon, you can remove a video from the playlist. iv. Using the and v. Using the icon, you can clear the playlist. icons you can move a video at a desired position in the playlist. vi. If you right-click on a video name you can play, add, remove, clear, or reset the playlist. When you right-click a video and select play, the video plays within the Playlist tab. 3. In the Library tab, you can execute the following actions: i. Right-click a .mp4 file and select Play to play the file. ii. Right-click a .mp4 file and select Download and play to download and play the file from any location. Copyright © 2012 Kony, Inc. All rights reserved. Page 58 of 785 Getting Started Kony Studio User Guide - 2.1 iii. Right-click a .mp4 file and select Enque to add the file to the Playlist. iv. Right-click a folder and select Enque to add all the files within that folder to the Playlist. v. Right click on a folder or a .mp4 file and select Open File Location to view the file or folder location. Note: When you open a folder and view the .mp4 files you will observe that each file is 0 bytes. These files are fetched from the server. vi. If you have added a new file or a folder in the videos folder, click Refresh to view the file or folder in the Library tab. 3.3.16 Grid Layout View Grid Layout View allows you to set properties for widgets when you apply grid layout on any container widget except ScrollBox. For more information on using a Grid Layout, refer Applying Grid Layout. Opening the Grid Layout View 1. Within Kony Studio, navigate to Window> Show View > Other. The Show View dialog appears. 2. Type Grid Layout in the textfield provided. Copyright © 2012 Kony, Inc. All rights reserved. Page 59 of 785 Getting Started Kony Studio User Guide - 2.1 3. Select Grid Layout and click OK. The Grid Layout View appears. Alternate Procedure 1. Right-click any container widget and select Apply GridLayout. 2. Right-click the widget to which the layout is applied and select Layout Properties. The Grid Layout View Appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 60 of 785 Getting Started Kony Studio User Guide - 2.1 3.3.17 Enterprise Explorer The Enterprise Explorer enables you to view all the services defined within the workspace. It also enables you to add Web Services, SharePoint Servers, JSON services, and XML services. The purpose of having all the services in the workspace at one place is when you define a service using the Service Definition Tool, you can view all the services within the workspace and load them. Opening the Enterprise Explorer View 1. Within Kony Studio, navigate to Window> Show View > Other. The Show View dialog appears. 2. Type Enterprise Explorer in the textfield provided. Copyright © 2012 Kony, Inc. All rights reserved. Page 61 of 785 Kony Studio User Guide - 2.1 Getting Started 3. Select Enterprise Explorer and click OK. The Enterprise Explorer appears. Using the Enterprise Explorer View 1. To add a WSDL service, do the following: a. Right-click on Web Services, and select Add Web Service WSDL. The WSDL Service dialog appears. b. Enter a name for the WSDL service. c. In the WSDL URL field, click to add an *.wsdl file. d. Enter the Basic Credentials for the service. e. Click OK. 2. To add a SharePoint service, do the following: a. Right-click on SharePoint Servers, and select Add SharePoint Server. The SharePoint Service dialog appears. b. Enter a name for the SharePoint service c. Enter the Host name where the SharePoint server is located. d. Enter the required port name. e. Enter the protocol to be used to access the host. f. Enter the Basic Credentials. g. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 62 of 785 Getting Started Kony Studio User Guide - 2.1 Note: After you provide SharePoint server IP address and port, the IDE loads all the WSDLs exposed by SharePoint server. You can browse the WSDLs and their services associated with it. Users can view the WSDL service input and output parameters in the Web Service Definition Files. Input and Output parameters can be classes or primitive types. Note: If you have defined the credentials of the SharePoint server, it will show up within the Web Services folder. Expand the Web Services/SharePoint Server folder and click the service you want to add. For more information about defining SharePoint services WSDLs, refer Creating a Web Service. 3. To add a JSON or an XML service, right click on the JSON or XML service and select Add JSON Service or Add XML Service. The JSON or XML service dialog appears. 4. In the JSON or XML Service dialog add the following: a. Enter the ID by which the service can be viewed. b. Enter the URL for the service. c. Enter a group under which the service is added. 5. To add BAPI methods and functions, right-click the SAP Servers folder and select Add Server. The SAP Server Details dialog appears. For more information refer, Using SAP Servers. 6. To add Siebel functions, right-click the Siebel Servers folder and select Add Server. The Siebel Server Details dialog appears. For more information refer, Using Siebel Servers. 7. To add Mainframe(WebsphereMQ) Services, right-click the JMS/MQ Servers folder and select Add Server. The JMS/MQ Server details dialog appears. For more information refer, Using WebSphere MQ Server. 8. Click OK. 3.4 Emulators An emulator simulates a mobile device on your local machine. Emulators maintain the original look, feel, and behavior of the mobile device. An emulator duplicates the functions of the application so that the application behaves exactly the same as it would on actual mobile device. When you create an application in the IDE and build it, the IDE provides you the option of testing the application for appearance and performance. You need device emulators to do this. These emulators are provided by the device manufacturers or mobile platform vendors. Note: You should have the emulators configured to view or test an application on the emulators. For more information about configuring emulators, see Kony Studio Installation Guide. To configure emulators, follow these steps: 1. Go to Emulators view. 2. Right-click the required emulator and click Edit. Copyright © 2012 Kony, Inc. All rights reserved. Page 63 of 785 Getting Started Kony Studio User Guide - 2.1 3. Browse for the location of the emulator on the local machine in Emulator Info window. For more information about configuring the paths of the emulators installed on your machine, see Kony Studio Installation Guide. 4. Click Finish. After configuring the emulators is complete, the Emulators view is as shown below: Note: Only for Android, you have the ability to add an emulator of your own. For other emulators you can only map the path to the installed emulator. For more information about adding an Android emulator, see Adding Android Emulator. 5. When you build the application on a specific platform, a icon appears against each emulator on which the application was built successfully. In that case, the Emulators view is as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 64 of 785 Getting Started Kony Studio User Guide - 2.1 3.4.1 Adding Android Emulator The Android SDK installed in Eclipse does not include any pre-configured Android Virtual Devices (AVDs). When you want to run any application on the Android emulator, you need to create an AVD. AVDs are configuration options that let you simulate the Android mobile device in an efficient manner. You can create as many AVDs as per your requirement and map them to the emulator. Every AVD you create consists of the following: l A set of hardware options and configurations that define the features on the emulator. l Android platform; this can be standard Android platform or the one that comes with the Android SDK. l l Skin options that control the visual aspects of the emulator like screen dimensions, appearance, and so on. A dedicated storage area on your local machine. For more information about AVD, see http://developer.android.com/tools/devices/managing-avds.html To add an Android emulator for mobile, follow these steps: 1. Go to Emulators view. 2. Right-click Mobile under Android and select Add. Emulator Info window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 65 of 785 Getting Started Kony Studio User Guide - 2.1 Note: Kony Studio allows you to specify command line options for Android emulators. The command line options govern the way the emulator is displayed. For more information, see http://developer.android.com/guide/developing/tools/emulator.html. 3. Enter a name for the emulator under Emulator Name field. 4. Browse for the location of the pre-defined emulator under Location field. 5. Enter a name for the AVD under AVD Name if there is an AVD already created. Click Create AVD if you want to create a new AVD with the name you have entered. For more information about creating AVDs, see http://developer.android.com/guide/developing/tools/avd.html#creating. Note: Create AVD button is enabled only when you select the location of the emulator and enter a name for the AVD. Copyright © 2012 Kony, Inc. All rights reserved. Page 66 of 785 Kony Studio User Guide - 2.1 Getting Started i. Enter a Name for the AVD. This name should match the name you have entered in the above step. ii. Select the Target. The target can be: n Android 1.5 - API Level 3 n Android 1.6 - API Level 4 n Google APIs (Google Inc.) - API Level 3 n Google APIs (Google Inc.) - API Level 4. Important: The target must be Google APIs of required Android API level. For more information about API levels, see http://developer.android.com/guide/appendix/apilevels.html. iii. Browse and select the location of the SD Card. iv. Select a Skin for the AVD if required. v. Click Create AVD. 6. Enter the Command Line Arguments to launch this emulator. For more information about command line arguments for emulators, see http://developer.android.com/guide/developing/tools/emulator.html. 7. Click Finish. A new emulator for Android is created. This new emulator appears under the list of emulators as shown below. Copyright © 2012 Kony, Inc. All rights reserved. Page 67 of 785 Getting Started Kony Studio User Guide - 2.1 To create an emulator for Android tablet, follow these steps: 1. Go to Emulators view. 2. Right-click Mobile under Android and select Add. Emulator Info window appears as shown below: 3. Complete the procedure in the similar way you have done for a mobile emulator. 3.4.2 Adding BlackBerry Emulator Kony Studio provides you an option to add emulators for a selected version of BlackBerry JDK. This option helps the developers to the test the application on the required model of the mobile device supported by a specific JDK Version. To add a BlackBerry emulator, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 68 of 785 Getting Started Kony Studio User Guide - 2.1 1. Go to Emulators View. 2. Right-click BlackBerry -> <JDK Version> and select Add. 3. The Add Emulator window opens. 4. Browse and select the location of the emulator. Note: You must select the emulator that corresponds to the selected JDK version. For example, if you are adding an emulator for BlackBerry V4.2, you must select the 4.2 emulator. 5. Click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 69 of 785 Kony Studio Preferences Kony Studio User Guide - 2.1 4. Kony Studio Preferences The Kony Studio Preferences window lets you configure various preferences related to the IDE. 4.1 Launching Preferences Window 1. Launch Eclipse. 2. Open Kony Perspective. 3. Click Window -> Preferences. 4. Click Kony Dev Studio in the left panel. The Kony Studio Preferences panel appears on the right side of the window. 4.2 Configuring Kony Studio Preferences The Kony Studio Preferences panel has many options that need to be configured for the IDE and emulators to function. The following preferences are available in this window: l l Kony Dev Studio o Enable Skin Preview - instant preview is enabled if this option is checked. o Enable lua debugging - enables the application for debugging in Lua. o Widget ID Counter - an automated number that is incremented every time a new widget is added to the form. o Show Margin Details - displays the margin values set to the selected widget when you press Alt and double-click. o Show Padding Details - displays the padding values set to the selected widget when you press Alt and double-click o Show Render Details - displays the render values (On or Off) set to the selected widget when you press Alt and double-click. o Always Profile Application - enables you to profile an application. For more information, see Profiler. o Enable JavaScript Syntax validation - enables you to validate the syntax entered in the JavaScript modules. o Enable JavaScript type checker - enables you to view invalid JavaScript types, errors and warning in the Javascript modules. Build o Skip Code Generation and Do Packaging only - code is not generated and the application is just packaged. o Uninstall all web applications - if this option is checked, all the previously generated war files are deleted and a war file is built fresh for Mobile Web. Copyright © 2012 Kony, Inc. All rights reserved. Page 70 of 785 Kony Studio Preferences o Turn off Build Logs on Console - all the messages in the Console are turned off if this option is checked. o Clean and rebuild without warning - if you select this option, when you build the application a Clean and Rebuild All is performed without giving any warning to the user. o Validate XML while building - if this option is selected, Kony Studio validates (check for proper formation of the XML file) the XML files that have been generated while building the application. o Run Lua API Checker and type checker - if this option is selected, Kony Studio validates for the grammar and syntax of the APIs used in the application and displays errors, if any, on the console. This option is deselected by default. For more information, see API Checker/Type Checker. Code Generation Log level - specifies the level of logs required while generating the code for the application. The value can be: o o l l Kony Studio User Guide - 2.1 n Error - displays the errors. n Info - displays the information about the errors. n Debug - displays the debug tips for the errors. Specify paths for the following: n ImageMagick Home - Path to ImageMagick installation folder. n Android Home - Path to Android installation folder. n Palm Home n Qt Home n PlayBook Home. Debugger o IP Address - IP address of the computer on which you have built the application. o TCP Port - port number on which the debugger runs. o Client Socket Timeout - timeout in milliseconds after which the connection to client times out. Dialogs o Close Event Editor without warning - when you navigate to the function editor from the Event Editor, the Event Editor closes without warning, if this option is checked. Copyright © 2012 Kony, Inc. All rights reserved. Page 71 of 785 Kony Studio Preferences Kony Studio User Guide - 2.1 If you select Don't show this message again on this window, the option Close Event Editor without warning on the Kony Studio Preferences window is checked automatically. o l l Always save unsaved forms and update mappings when widget id is changed - if selected you will not be notified when you change the widget ID and the mappings will be updated automatically. Embedded Server o Jetty IP Address - ip address of the Jetty Server o Jetty HTTP Port - HTTP port on which the Jetty Server runs. o Jetty HTTPS Port - HTTPS port on which the Jetty Server runs. Preview Configuration: Enables you to set the configuration parameters to enable Auto Preview for Rich Client platforms. Copyright © 2012 Kony, Inc. All rights reserved. Page 72 of 785 Utility Functions Kony Studio User Guide - 2.1 5. Utility Functions To view the utility functions. right-click the project in Applications view area and navigate to Utilities. Kony Studio provides you with the following utility tools that help you do different operations: l l l l l l l Upgrade Actions - required when you upgrade the projects built on earlier Kony Studio versions. From 5.0.04 onwards when you build a project built on an earlier version of Kony Studio, a message appears stating that the project will be upgraded to the current version. Proceeding with the upgrade actions may result in changes in the folder structure. Upgrade Project to Current Version - required when you upgrade your project built on Kony Studio. Margins/Paddings - copies or replaces the margins and paddings applied to a specific widget to all the selected platforms. Platform Porting: allows users to copy all the properties of all the widgets within the application from one platform to one or more platforms without modifying the code base. For example, if an application is developed for iPhone it can be easily ported to Blackberry, iPad or any other platform. Edit All Properties (Widgets, Containers) - edit the properties of all the forms, the widgets within the forms at one go instead of editing separately in the Properties window. You can filter the widgets by widget type, widget property, widget category, or the whole word. Form Merge Tool - enables you to compare a form with another form. Generate Widget Statistics (Excel) - generates the statistics about the forms and the widgets within the application. The statistics is generated in a .xlsx format in <workspace>/<application>/docs folder. The file has the following fields: l Widget - name of the widget l ID - unique id of the widget l Size - size of the widget in pixels l l Rendered On - list of platforms on which that widget is rendered on (All if rendered on all platforms) Rendered Off - list of platforms on which that widget is rendered off (None if rendered off on all platforms) l Visible - true or false l Screen Level Widget - true or false. Note: The file has different sheets where each sheet corresponds to a form in the application. l Compare Files - compares any two files like .kl file, .lua files, .xml files (generated). The comparison can be done at the folder level also. Note: Make sure you use the same type of file for the compare operation. Else the results are unpredictable. l Launch Diff Tool - compares two plug-ins. The luasrc / jssrc folder of the two plug-ins is compared Copyright © 2012 Kony, Inc. All rights reserved. Page 73 of 785 Utility Functions Kony Studio User Guide - 2.1 and the tool highlights the changes (additions, deletions, and modifications). Note: This option is visible only if you have built the application using two different plug-ins. 5.1 Edit All Properties This feature allows you to edit the properties of the all the forms, the widgets within the forms at one go instead of editing separately in the Properties window. You can filter the widgets by widget type, widget property, widget category, or the whole word. 5.1.1 Editing all properties in an Application To edit all the properties in an application, follow these steps: 1. Right-click the project in Applications view area and navigate to Utilities > Edit All Properties (Widgets, Containers). The Edit All Properties (Widgets, Containers) window appears. All the forms in the application are displayed in the Left pane. All the properties of a selected form are Right pane. 2. In the Filter area, enter required values in the fields. The Filter Area enables you to filter the following: l l l Widget: Enables you to view a certain widget in the Right Pane. Only the widget entered in the Widget field is displayed in the Right Pane. Category: Enables you to view the categories of widgets in the Right Pane. Only the category entered is displayed in the Right Pane. The widgets properties are categorized by their General properties, Appearance, Events, and the Platform names. You have to click the expand icon on the top-right to view the categories. Property: Enables you to view the properties of widgets in the Right Pane. Only the property entered is displayed in the Right Pane. The widget properties are the common properties and Copyright © 2012 Kony, Inc. All rights reserved. Page 74 of 785 Utility Functions Kony Studio User Guide - 2.1 the platform specific properties of a widget. You have to click the expand icon on the top-right to view the properties. l Whole Word: Enables you to search the widget or property by the entire keyword entered in the Widget/Category/Property field. Note: Ensure that all the properties are collapsed before applying filter. If all the properties are expanded, it takes more time for the items to be filtered. 3. To change all the properties or widgets within the same form, do the following: i. Change the property of a single widget. The widget and its changed property is displayed in bold. ii. Right-click on the property and select Apply All. The changes you have made to the property for a single widget are applied to all the widgets on the form. 4. To change a property for a widget on all forms in an application, do the following: i. From the Left Pane select the forms you want the change to be reflected in ( by holding down the Ctrl key. ii. Change the property of a single widget. The widget and its changed property is displayed in bold. iii. Right-click on the property and select Apply All. The changes you have made to the property for a single widget are applied to all the widgets on all the selected forms. 5.2 Platform Porting During the initial stages of the Application Development Lifecycle , you may focus on developing the application only on a few platforms. In such cases, since the properties like margins, paddings, and skins are an important part of the UI, it can be challenging to replicate these properties from one platform to other platforms. You may want to port the application to other platforms when the development is complete. Kony Studio provides you the option to port an application along with its properties from one platform to another platform. This feature allows users to copy all the properties of all the widgets within the application from one platform to one or more platforms without modifying the code base. For example, if an application is developed for iPhone it can be easily ported to Blackberry, iPad, or any other platform. 5.2.1 Porting an Application To port an application, follow these steps: 1. Right-click the project in Applications view area and navigate to Utilities > Platform Porting. 2. Platform Selection Page screen appears. Select the Source Platform from the drop-down and select Target Platform. Copyright © 2012 Kony, Inc. All rights reserved. Page 75 of 785 Utility Functions Kony Studio User Guide - 2.1 3. Click Next. Properties Categories screen appears. l Platform specific properties: Copies the properties that are compatible in both the platforms. For example: If you are porting an application from iPhone to Blackberry, you have a button with the property Display Text visible as false. After porting in Blackberry the Display Text will be false. If the source platform has a button property Glow Effect, since this property is not available in Blackberry, it will not be ported. Note: Platform specific properties that are not available in target platform will not be ported. l l Skins: Copies the skins that are available in the source platform. The skin will be forked on the target platform only if the skin is forked in the source platform. You can fork the skin by changing the Font Size Multiplier (%) in Skin Clone Properties screen. If the Font Size is not changed, the default skin will be applied. Paddings: Changes the paddings if they are defined in the source platform. To apply the paddings of iPhone to other platforms below is the calculation. The conversion is 1% = 3.2 pixels. l l Render: Specifies if the widget code must be included in the platform when the code is generated. Preprocessor Actions: Processes input values to produce output, which is used as input to another program. Note: Preprocessor decisions cannot be ported across platforms in successive porting iterations. They can be ported only for the first instance. l Application Menu Features: Contains features that apply to the application as a whole, rather than to a specific application screen or window. The forms within the application are modified accordingly after the porting operation. 4. Click Next. The Portable Properties Page appears. Select the forms that you want to port in the leftside pane. Select the required widgets in the right-side pane. When you expand the form, you can also select the property category that you want to port. For example, the properties of the form are categorized as General, Appearance, and platform-wise. Copyright © 2012 Kony, Inc. All rights reserved. Page 76 of 785 Utility Functions Kony Studio User Guide - 2.1 l Click to select all the forms, widgets, and properties for porting. l Click to deselect all the forms, widgets, and properties for porting. l You can filter the forms and widgets by Category, Property name, or Whole Word. 5. Click Next. On the Margins and Paddings Percentage page, specify the margins and paddings multipliers. l Margins: Changes the margins if they are defined in the source platform. To apply the margins of iPhone to other platforms below is the calculation. The conversion is 1% = 3.2 pixels. For example, if you are porting from Blackberry to iPhone then, The following images illustrate the difference in margins (before and after applying margins) through porting. Copyright © 2012 Kony, Inc. All rights reserved. Page 77 of 785 Utility Functions Kony Studio User Guide - 2.1 Copyright © 2012 Kony, Inc. All rights reserved. Page 78 of 785 Utility Functions l Kony Studio User Guide - 2.1 Paddings: Changes the paddings if they are defined in the source platform. To apply the paddings of iPhone to other platforms below is the calculation. The conversion is 1% = 3.2 pixels. 6. Click Finish. 7. In the console window you can view a list of properties that are ported. 8. Porting operation generates the details of the porting in a spreadsheet. The spreadsheet will display the properties and its corresponding previous value and new values. The spreadsheet is generated in the <workspace>/<application>/docs folder. The spreadsheet will contain the following: l Margins l Paddings l Skins l Platform Specific Properties l App menu features l Preprocessor decisions l Pre-appinit l Post-appinit l Splash screen. Copyright © 2012 Kony, Inc. All rights reserved. Page 79 of 785 Utility Functions Kony Studio User Guide - 2.1 The following image shows a sample spreadsheet with the details of porting. The excel sheet will display the Form/Widget name, its property, its old value and new value. Similarly, you will find other platform details in different tabs. 5.2.2 Limitations of Porting Widgets and preprocessor decisions cannot be ported across platforms in successive porting iterations. Images in the resources folders can be ported only for the first time. While porting, existing images of one platform will be copied to the target platform, but extra images or resolution specific images will not be created. For example: User is porting from a non-resolution specific platform to a platform, which requires resolution specific images, user has to create those images and copy to respective resolution folders. 5.3 Form Merge Tool The Form Merge Tool enables you to compare a form with any other form. The forms you want to compare must exist in the same workspace. You can compare two forms of the same application or two forms of different applications that exist in the same workspace. To compare forms using the Form Merge Editor: Copyright © 2012 Kony, Inc. All rights reserved. Page 80 of 785 Utility Functions Kony Studio User Guide - 2.1 1. Right-click the project in Applications view area and navigate to Utilities >Launch Form Merge Tool. The Form Merge Editor appears. 5.3.1 Compare Settings You can perform any of the following operations using the Compare Settings area: l l l l l Save: (Disabled) Saves the changed form. This property is enabled only when you port a widget or properties from one form to another. Save As: Enables you to save the merged forms. When you click the Save As icon, the Save Merged Form dialog appears. The form on the left side is saved by default. To save the form on the right, select the Save Right Form checkbox. Clear and Reload Model: Discards all the changes made to the forms in either sides and reloads them in the Comparison Editor. Toggle View: Enables you to toggle between the Tree View, Graph View, and the Default View. Link Left and Right View: Enables you to relate the widgets between the two forms. For example if a button is present on form1 and not present on form2 when you port that button to form 2 and you click on the button on form1 in the Tree View or Graphical View, the corresponding button is highlighted on form 2. Copyright © 2012 Kony, Inc. All rights reserved. Page 81 of 785 Kony Studio User Guide - 2.1 Utility Functions Similarly if you copy a widget or a property from the left form to the right form or from the right form to the left form and enable the Link Left Right View, whenever you click that particular property or widget in one form the corresponding widget or property is highlighted in the other form. Note: The Link Left and Right View or vice versa works only for widgets having the same ID on both forms. 5.3.2 Filter Area Enables you to view only those widgets in the Tree View whose filter values are entered in the Filter Area. This property is useful when you have multiple widgets on the form and you want to edit properties of only certain widgets or edit certain properties of all the widgets. The Filter Area enables you to filter the following l l l l l Widget: Enables you to view a certain widget in the Tree View. Only the widget entered in the Widget field is displayed in the Tree View. Category: Enables you to view the categories of widgets in the Tree View. Only the category entered is displayed in the Tree View. The widgets properties are categorized by their General properties, Appearance, Events, and the Platform names. Property: Enables you to view the properties of widgets in the Tree View. Only the property entered is displayed in the Tree View. The widget properties are the common properties and the platform specific properties of a widget. Hide Properties: Enables you to hide the properties of widgets in the Tree View. Whole Word: Enables you to search the widget or property by the entire keyword entered in the Widget/Category/Property field. 5.3.3 Tree View The Tree View represents a hierarchical view of widgets and properties for each of the forms. The Tree View enables you to compare widgets of the forms using the hierarchy. For a detailed comparison for each of the widgets, click the icon in the Tree View and click the widget whose properties you want to view. If you want to view all the properties for all the widgets, click and Expand All. If certain widgets are there on form1 and not on form2, the extra widgets on form1 are denoted with a against them. Similarly all the widgets on form 2 not there in form 1 are denoted by against them. All the conflicts or modified data in the forms are denoted by a against the conflicted widget, category, or property. . If a widget(with the same ID) is present on two different parent containers on two different forms, it is denoted by a against it. For example, if a button with same ID is present on form1 in an HBox and present on form2 by itself , the button is denoted with a against it on both forms. In the hierarchy if a widget(with the same ID) is present form1 and not on form2, the widget is denoted on form2 with a against it. You can execute any of the following actions using the Tree View: l Expand All: Expands all the widgets and the corresponding categories. This feature works only if you click the Show only conflicts and modified data icon or the Collapse All icon first. Copyright © 2012 Kony, Inc. All rights reserved. Page 82 of 785 Utility Functions l l l l l l Kony Studio User Guide - 2.1 Collapse All: Collapses all the widgets and the corresponding categories. This feature works only if you click the Expand All icon first. Copy all changes on selection to left: Enables you to copy any widget or property selected on the left form to the right form. Copy all changes on selection to right: Enables you to copy any widget or property selected on the right form to the left form. Show only conflicts and modified data: Displays all the conflicts and modified data on both forms. If you right-click against a widget or a property, you can Expand All or Collapse All the widgets and properties. You can also delete widgets and launch the Text Diff tool which provides a text comparison of the forms. Change the property of a widget on a form by clicking on the property in the Tree View. Note: It is recommended to port widgets from one form to another using the Graphical View. For example if on form1 a button is placed in an HBox, and you want to copy the button to form 2 which does not have an HBox, the button will take the entire remaining space on form2. Thus for better visual representation, use the Graphical View instead. 5.3.4 Graphical View The Graphical View presents a visual representation of widgets of the forms. The Graphical View enables you to compare widgets of the forms visually. To copy a widget from one form to another click the Toggle Copy Mode button present at the bottom of each form. Once the toggle mode is enabled a notification appears at the bottom right hand corner of the screen. To copy a form from left to right select the Toggle Copy Mode button on the left form and drag the widget across to the form on the right. To copy a form from right to left select the Toggle Copy Mode button on the right form and drag the widget across to the form on the left. You can also have the Toggle Copy Mode for forms on either side enabled at the same time. Using the Toggle Copy Mode you can also copy widgets within the same form as well. Any widget you click in the Graphical View automatically corresponds to the widget in the Tree View. Copyright © 2012 Kony, Inc. All rights reserved. Page 83 of 785 Kony Studio User Guide - 2.1 Moving between Releases 6. Moving between Releases When you work on Kony Studio, you have the option to: l upgrade to a newer version. l move back to an older version from a newer version. 6.1 Important Considerations The following are a few important considerations before you upgrade to the latest version of Kony Studio: l Ensure that Android SDK has been properly installed. For more information, see Kony Studio Installation Guide. l Rename all the resources to follow the naming convention. l Ensure that you use only PNG or JPEG format for the images (preferably PNG). l Execute the Upgrade Actions. Important: When you build older versions of any application (built on Kony Studio versions 2.6 and earlier), the latest version of Kony Studio changes the names of ifdef platform statements to the new names. Be sure to modify your code if required to avoid breaking of the application with this change. Important: Take a backup of your code base (for applications built on Kony Studio versions 2.6 and earlier) before building the application in Kony Studio 5.0 and above. The changes made to the ifdef platform statements in Kony Studio 5.0 and above are irrevocable. The following table explains the ifdef platform names: JavaScript: ifdef Platform Names in Kony Studio 5.0 and above iphone android bb j2me winmobile wap symbian palm spaip spaan spabb spabbnth spawinphone8 spawindows spatabwindows Lua: ifdef Platform Names in Lua: ifdef Platform Names in Kony Studio 3.0 and above versions 2.6 and earlier m4iphone m4android m4bb m4j2me m4winmobile m4wap m4symbian m4palm m4spaip m4spaan m4spabb m4spabbnth m4spawinphone8 m4spawindows m4spatabwindows iphone android bb j2me winmobile wap symbian palm SPA iPhone SPA Android SPA Blackberry SPA BlackBerry NTH SPA Windows 8 Phone SPA Windows SPA Windows Tablet Copyright © 2012 Kony, Inc. All rights reserved. Page 84 of 785 Kony Studio User Guide - 2.1 Moving between Releases JavaScript: ifdef Platform Names in Kony Studio 5.0 and above spaipad spatabandroid spaplaybook desktopweb Lua: ifdef Platform Names in Lua: ifdef Platform Names in Kony Studio 3.0 and above versions 2.6 and earlier m4spaipad m4spatabandroid m4spaplaybook m4desktopweb SPA iPad SPA Android Tablet SPA PlayBook Desktop Web 6.2 Upgrading to a Newer Release From Kony Studio R2.5 onwards, the forms within an application are categorized under mobile and tablet channels separately. If you upgrade from an older version of Kony Studio to R2.5 and above, you have to manually perform actions that execute the following tasks automatically specific to the upgrade: l Upgrade Actions (this action is required when you upgrade your project built on earlier versions to the current version) o moving all forms from forms folder to forms/mobile folder o setting onScreen property to false for all Wheel Calendar widgets. For more information about this property, see Kony Widget User Guide. o setting transparency for forms and popups during postshow to 100. For more information about this property, see Kony Widget User Guide. Note: Execute this action for projects created with Kony Studio version 2.5 and earlier. Important: If you do not perform this task, the forms within an application will not be moved to forms/mobile folder (for an existing application) resulting in an error when you try to build the application. l Upgrade Project to Current Version (this action is required when you upgrade your project built on Kony Studio to the current version) o updating the platform names in ifdef statements o updates the format in which bindings are generated. Earlier it was stored in a nBinding tree format and now from version 3.1 onwards, it is in a readable format. Note: Execute this action for projects created with Kony Studio versions prior the current one. To prepare the application for upgrade, follow these steps: Important: Executing the upgrade tasks is a one-time process. You must do this the first time when you want to build and run your older applications with latest version of Kony Studio. 1. Go to Applications View. 2. Select the required application. Copyright © 2012 Kony, Inc. All rights reserved. Page 85 of 785 Moving between Releases Kony Studio User Guide - 2.1 3. Right-click the application and select the appropriate upgrade option based on the version of Kony Studio that was used to create the project (Upgrade Actions or Upgrade project to 3.1). 4. Click Proceed to confirm the automatic execution of the upgrade task. Note: When you build an older application (application developed in Kony Studio versions 5.0 and earlier) in Kony Studio 5.0 or above versions for the first time, internationalization folders are automatically created in the resources folder. 6.3 Migrating from Newer Release to Older Release Important: After migrating, if you plan to use the same workspace as previously used, we recommend to delete all the contents present in the <workspace>/webapps folder. When you migrate from newer release of Kony Studio (3.1) to an old release (releases 2.3 or earlier), for the emulators to work properly, there are a few steps you need to perform manually. 1. Navigate to <workspace>/<application>/forms/mobile folder. 2. Move all the forms located under the mobile folder to the forms folder. 3. Navigate to <workspace>\.metadata\.plugins\org.eclipse.core.runtime \.settings folder. 4. Open the com.pat.tool.keditor.prefs file. 5. In that file, delete the following content: <Tablet checked\="true"> ...<GalaxyTab checked\="true" location\=""/> </Tablet> 6. Change the <WindowsMobile> tag to <WindowMobile> tag. Make sure this is changed for all occurrences. Copyright © 2012 Kony, Inc. All rights reserved. Page 86 of 785 Kony Studio User Guide - 2.1 Working with Applications 7. Working with Applications You can develop applications to perform various operations, using different application logic, and for various domains and platforms. Applications are also known as projects. Application and project are used interchangeably. Any application developed in Kony Studio has the following components: l l l User Interface (UI) Components - forms, popups, images, and widgets Non UI Components - skins, services, service definition file, project properties, internationalization content User Defined Components - user-written code modules and custom services. The application components (files) are physically available on the computer at the following location (s): Object File Format Location of the File l Forms <workspace> /<project>/forms /mobile for mobile related forms .kl l <workspace> /<project>/forms /tablet for tablet Remarks contains details of all the form properties, its widgets and their properties related forms contains details of all the skins used within the project Skins .xml <workspace>/<project> Service Definition File .xml <workspace>/<project> /services Resources binaries <workspace>/<project> /resources Internationalization (i18n) Content .prop JavaScript Code Modules .js For a sample skin.xml file, see the Appendix Sample Skin.xml File. a single xml file that contains the details of all the services in the project represents all the images used within the project, the files related to FFI (stub templates and xml files) <workspace>/<project>/ a resources/i18n <workspace>/<project> /modules/js Copyright © 2012 Kony, Inc. All rights reserved. Page 87 of 785 Kony Studio User Guide - 2.1 Working with Applications Object File Format Location of the File Remarks .lua <workspace>/<project> /modules/lua a Project Properties File .xml (projectprop.xml ) <workspace>/<project> contains all the properties defined at the project level <workspace>/<project> contains metadata of all the skins within the project Lua Code Modules Project Skins .xml (projectskin.xml ) This chapter explains all the tasks related to applications starting from creating an application to publishing an application. You can perform the following tasks after reading this chapter: l Create an application l Add forms to an application l Add widgets to a form l Configure widget properties l Import custom fonts l Work with skins l Fork forms l Add resources to an application l Add code module to an application l Add application menu l Configure project properties l Build application l View application on emulators l Publish application. 7.1 Categories of Applications Mobile applications can be built and deployed using various techniques and approaches. One extreme is to use the native SDK to build Enterprise applications, while the other extreme is to use traditional web technologies to build mobile web applications. Mobile applications can also be built using the methods that fall in between these two extremes. These methods use a mixture of both native and web technologies to achieve the same. Kony Platform provides complete flexibility to choose different packaging and deployment modes according to the needs of the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 88 of 785 Working with Applications Kony Studio User Guide - 2.1 The following are the different approaches you can use to build applications using Kony Studio: l l l l l Native Native application resides on the device, where all the forms and UI definition of the widgets is packaged along with the application. Traditional Mobile Web Mobile Web application is built using traditional server-side web technologies and is primarily executed on the server-side while the client browser only renders the HTML content. Though we can embed client-side logic using the JavaScript, this code is minimal when compared to the entire application size. Hybrid Hybrid application is a version of the native application, where all the layout is rendered using the native shell provided by the respective platforms (UIWebView for iPhone and Browserfield for BlackBerry), instead of the native SDK widgets. The native SDK is invoked only for native device features like Camera, Contacts, and so on. Mixed Mode Mixed Mode application is partly a native application and partly a web-based application. In the native part of the application, some of the forms are rendered using UIWebView and Browserfield, while other forms are rendered using the Native SDK. The developer can pick and choose the forms that need to be native or web-based. The web-based forms can be either packaged statically along with the application or loaded from a URL dynamically. Single Page Application (SPA) Single Page Applications (SPA) are a type of web applications, in which all the HTML, CSS, and JavaScripts necessary for the application are retrieved with a single page load. The page does not automatically reload during user interaction with the application or control the transfer to another page. The application requires server interaction only for data retrieval. Unlike a traditional mobile web application, the browser executes all the application logic on the clientside. The logic includes validations, UI rules (hiding or showing fields), form transitions/navigations, and so on. In a SPA, all the application screens are expressed as a JavaScript model/CSS (unlike JSP, ASPX in a typical Mobile Web application). This JavaScript model is downloaded to the client-side with the first page download and resides on the client for the lifetime of the session. l Desktop Web Desktop Web Applications are a type of application that run on the web browser of the desktop. The supported browsers are as follows, Firefox v 3.6 and above, Internet Explorer 8 and above, Safari,and Chrome. Desktop Web applications can only be built for JavaScript projects. Copyright © 2012 Kony, Inc. All rights reserved. Page 89 of 785 Kony Studio User Guide - 2.1 Working with Applications The characteristics of each of the application type are denoted by the colors specified below in the following table: Legend l - applicable l - partially applicable l - not applicable. Characteristics Is available as a natively deployable package (.app , .apk, .cod, and so on) Utilizes the native widgets , such as the title bar, application menu, ListView, TableView, Searchbar, and so on Has access to native device function like GPS, Camera, Contacts, Accelerometer, Mangnetometer, Encryption libraries (and thousands of other native SDK functions) Can be distributed through the App stores (Apple iStore, Android MarketPlace, BlackBerry App World, and so on) UI elements (Forms, images,and i18n content) are packaged along with the application Server access only for downloading data Application Category/Type Traditional Mixed Desktop Native Mobile Hybrid SPA Mode Web Web 1 2 3 2 7 4 5 6 _________________________________________________________________ 1 Only the forms whose nature is set as native utilize the native widgets. 2 Only the APIs exposed and implemented as part of the HTML5 Specification. 3 Native SDK functions are accessed using JavaScript Bindings. 4 If the nature of the form is set to dynamic, the forms and UI elements are downloaded from the server at runtime. 5 Both UI definition and business data are accessed from the server. 6 After the first page is downloaded, the Server is accessed only for fetching business data. 7 Only GPS is supported. Copyright © 2012 Kony, Inc. All rights reserved. Page 90 of 785 Working with Applications Kony Studio User Guide - 2.1 7.2 Developing Single Page Applications (SPA) A Single Page Application (SPA) represents a special type of the web applications, in which all the HTML, CSS, and JavaScript files necessary for the application are retrieved with a single page load. The page neither re-loads automatically during user interaction with the application, nor transfers the control to another page. The application requires server interaction only for retrieving data (exposed as JSON, WebServices, or Data services). Kony Platform serves the devices with SPA version of the application using the device detection logic. The platform falls back on the traditional Mobile Web platform for devices that do not have HTML5 compliant browsers. Once the first page is downloaded, an SPA behaves the same way as that of a client-side model application. Note that a Lua Virtual Machine does not run on the client side, and all the Lua code is converted to JavaScript (ECMA 262) at design time (in Kony Studio). Each form (and its widget hierarchy) is represented as a JSON object. This model is then populated at runtime with the data that drives construction of the resulting Document Object Model (DOM). This platform covers a wide spectrum of devices available in the market. These include: l iOS 4.0, 5.0, 6.0 l Android 2.2 and above( Except 2.3 emulators) l BlackBerry 6.0, 7.0, 10(Touch Devices) l iPad and Android 3.0 tablets l BlackBerry PlayBook. l Windows 7.2.1 Workflow Traditional Mobile Web Application Copyright © 2012 Kony, Inc. All rights reserved. Page 91 of 785 Kony Studio User Guide - 2.1 Working with Applications Single Page Application 7.2.2 Comparison with Traditional Mobile Web The following table compares the characteristics of a traditional Mobile Web application with an SPA: Traditional Mobile Web Single Page Application Lua is converted to JavaScript and executed on the Application logic executed as Lua on the Server Side client (browser) side All execution happens on the client-side (JavaScript Every action would require a server call to execute function corresponding to the Lua function is the Lua function and to load the new/refreshed page executed on the client-side) Supported only on iPhone 4.x, Android 2.3, and Supported across devices BlackBerry 6.0 and 7.0 (Touch Devices) devices Supports HTML5 features like GeoLocation and Supports HTML5 features like GeoLocation and CSS3 Gradients CSS3 Gradients Cannot leverage HTML5 features like localstorage, Leverages all the HTML5 features WebSQL APIs) Does not support screen transitions, animations, and Supports screen transitions and animations docked headers and footers 7.2.3 HTML5 in SPA HTML5 Features Features Benefits HTML5 Application Caching (AppCache) support Allows SPA to look like native applications. Allows for cross-session and single-session local data storage with Web SQL. Allows for new input types such as number, range, email, url, data picker, color, and many more. Allows for improved structure with section, header, footer, aside elements and more. Allows video and audio objects to be presented through HTML5 with no plug-in. Browser must support one of the supported formats of each and the source media must be available. HTML5 Local Storage and Session Storage HTML5 Input Elements HTML5 Markup (Semantic) Elements HTML5 Video and Audio elements Copyright © 2012 Kony, Inc. All rights reserved. Page 92 of 785 Kony Studio User Guide - 2.1 Working with Applications CSS3 Features Features Benefits CSS3 2D and 3D Transformations - predefined and Allows for turning, spinning, stretching, scaling and custom elements moving form elements. CSS-targeted media queries Allows optimizing for target device's DPI. Allows for dynamic gradients rather than static images CSS3 Gradients, Rounded Corners, Shadows and image UX effects. Essentially these are rules that can be applied to CSS Selectors specific widgets when they satisfy a certain condition. Allows for transitions of container elements like form, CSS Transitions popups. Allows for sizing the background images when applied CSS Background Sizing to container elements like form,box, popup. Handling Touch Devices Features Handle touch events in HTML5-capable browser Support for Gestures API Third-party JavaScript mobile-optimized widgets from vendors such as JQuery, SproutCore, Sencha and Dojo can be easily leveraged Geolocation APIs, LocalStorage APIs, WebSQL APIs History APIs Native JSON Parsing Benefits Resolve as tap, double-tap, long press and swipe events. Action touch events raised through the browser Functionality is expanded for the developer to choose what they want to use, managed through a single codebase. Mobile browser is now able to locate user with permission granted for one or multiple sessions. Enables cross-browser functionality for URL history which otherwise would not be added on a hash change. JSON is used for browser communication as native applications currently do. 7.2.4 Handling Multiple Form Factors and Resolutions Image Assets based on Dots Per Inch (DPI)/Form Factors The applications must have right image assets to handle various DPIs. SPA platform enables automatic detection of the device DPI by default and requests for the right set of images based on the DPI. You need not write additional code for this purpose. In case of the devices with different form factors but same DPI, the SPA platform uses the device screen width as a factor while requesting the appropriate image assets. SPA platform also handles screen orientation specific asset requests. Copyright © 2012 Kony, Inc. All rights reserved. Page 93 of 785 Working with Applications Kony Studio User Guide - 2.1 Gestures using DPI Besides using the DPI for the resource identification, SPA platform also uses DPI for calculating the threshold limits to identify various gestures like swipe, scroll, tap, and double-tap. 7.2.5 Manifestations of SPA The following are different manifestations of an SPA: l l l Hybrid In this mode, the SPA application runs inside the native shell applications of iPhone and Android. The hybrid mode, enables the developer to take full advantage of the native features offered by various platforms without losing the comfort of having an HTML5 compliant application. For more information, see the chapter Developing Mixed Mode Applications. Mixed Mode Kony Platform offers seamless data exchange between the forms of different types, such as native forms or traditional mobile web forms, giving the end users a single application usage experience. At the same time it provides great freedom to the customers/developers to decide which forms to be native, SPA or traditional web depending, on their unique business requirements. For more information, see the chapter Developing Mixed Mode Applications. Native BlackBerry PlayBook Blackberry playbook offers Adobe AIR based runtime as one of the runtime options. SPA applications which are fully JS based, when passed thru the playbook software chain are converted into native AIR based applications. These applications have access to the native features offered by the PlayBook. 7.2.6 Design Guidelines for a Single Page Application The following are the design guidelines you must adhere to while developing a Single Page Application: Use net.invokeserviceasync API to invoke services Since browser implementation of JavaScript is single threaded, all the network calls must be asynchronous, so that the UI is not blocked and responds to the user actions till the service call completes. Avoid using Lua table that has both list and key-value pairs Bad Example local foo = {1,2,3,4,5} foo.text = "Bar" - will get added to the hash part Good Example local foo = {1,2,3,4,5} Copyright © 2012 Kony, Inc. All rights reserved. Page 94 of 785 Working with Applications Kony Studio User Guide - 2.1 local newfoo = "Bar" Avoid dependency on multiple return types from a Lua function or API Bad Example local firstname,lastname =readName(); function readName() return "foo","bar"; end; Good Example function readName() local names=readName(); local firstname=names[0]; local lastname=names[1]; return names{"foo","bar"}; end; 7.3 Porting Applications to SPA This section provides you the steps involved in porting an existing application built on Kony Platform to SPA channel. Unlike other channels that the platform supports, SPA channel has some unique requirements as it runs within the browser context using JavaScript as the language. Some of the restrictions provided in this section are also applicable for the applications built from scratch for SPA. 7.3.1 Need for Porting SPA channel requires the conversion of Lua code into JavaScript. This conversion is required to make full use of the browser's advanced JavaScript engines and also the HTML5 features and capabilities that the device browsers provide. To convert the Lua code written by the developers as part of the client logic, the Kony Platform provides Native Code Generation mechanism that converts Lua to JavaScript. 7.3.1.1 Lua Table In Lua, the language has only one datastructure - Lua Table. This table can be used as an array or a key-value hash or both at the same time. The language provides mechanisms to iterate through these using ipairs and pairs. Copyright © 2012 Kony, Inc. All rights reserved. Page 95 of 785 Working with Applications Kony Studio User Guide - 2.1 In JavaScript, there is no equivalent structure for Lua Table that can accept both array and key-value pair at the same time without introducing a custom structure and maintaining the Lua semantics on that structure. This requires the JavaScript developer to maintain the Lua semantics in JavaScript. For this purpose, it is recommended to avoid using a Lua Table that has both array and key-value (hash) part at the same level. This enables the code conversion tool in Kony Platform to treat a Lua table (array) as a normal array object in JavaScript and the one with key-value pairs as an object. SPA platform uses the Lua table semantics for all of the table specific APIs. 7.3.1.2 Network Library In a JavaScript based application, the only mechanism available to make a network call is through AJAX, which is an asynchronous mechanism. Using the current Kony APIs, the developer can make network calls using either synchronous or asynchronous mechanisms. Synchronous behavior is not supported in JavaScript as the JavaScript engine does not wait for the response from the network call and continues to execute the code written immediately after the network call. In Lua, when the developer writes code that invokes services synchronously, the developer expects the platform to wait until the response from the network service call is received and then execute the subsequent code. This code, when converted to JavaScript, will fail as the service call is made through AJAX and the JavaScript engine does not wait for the response but continue with the execution of code, leading to errors. To avoid these issues: l Develop the applications using the asynchronous network API. l Convert the network APIs of the existing applications from synchronous to asynchronous mechanism. 7.3.1.3 Statements The Native Code Generation engine uses AST based mechanism to build the tree for the Lua code written by the developers. This imposes the following restrictions: 1. Nested functions, as allowed in Lua, should be avoided. 2. Lua allows the developers to use the same variable for different datatypes. This should be avoided, as the Native Code Generation fails to identify the correct data type of the variable when converting to target language. function f() x = 5; x = "str"; end; Native Code Generation engine cannot convert this code into the target language. 3. All Lua code should be inside the functions. There should not be any code/statements outside the functions in the entire application. x = 5; function f() print(x); end; Copyright © 2012 Kony, Inc. All rights reserved. Page 96 of 785 Working with Applications Kony Studio User Guide - 2.1 Native Code Generation engine cannot convert this code into the target language. The variable x will be undefined in the target language. 4. Multiple return values, though supported by Lua, cannot be converted into target languages by the Native Code Generation engine. Developers should not return multiple return values from their functions. API's returning multiple return values will be deprecated from the platform API. 7.3.2 Porting Steps This section explains the steps you need to follow to port the applications: 1. Ensure that the application does not use any of the reserved keys available at the end of this chapter. 2. All the network calls used in the application should be converted from synchronous to asynchronous mechanism. The developer should use the callback for handling code that operates on the network call response. 3. Mixed mode Lua table should be changed to have either only array or hash parts. 4. ipairs should be used for iterating through Lua tables which have only array part. pairs should be used for Lua table which have only hash part. 5. Ensure that all the statements in the application are used/defined from within the function blocks. 6. Build the application with the above changes and test if the application is running successfully on the existing platforms for which the application was originally built. 7.3.3 SPA Specific Tasks This section describes the SPA specific tasks that you need to perform: 1. Use the Kony Studio Porting Tool to port the margins/paddings and widgets from the current platform to SPA. 2. For writing any SPA specific code using preprocessor (ifdef) statements, use the preprocessor keys on 3. Important Considerations. 4. Perform the SPA specific UI modifications like: i. Adding form/popup level transitions. ii. App Menu. iii. Docked header/footers. 7.3.4 Restricted Keyword List All restrictions related to namespaces and keywords remains as is. Kony is a new namespace that is added to the restricted set. Any variable cannot be declared with name "kony". Copyright © 2012 Kony, Inc. All rights reserved. Page 97 of 785 Kony Studio User Guide - 2.1 Working with Applications The following table provides a list of keywords that should not be used in the Lua application code by the developer: abstract assert advertisement boolean box break button byte calendar camera case catch char instanceof interface import int label line link listbox local long map math menu volatile web while try until void public radiobuttongroup checkboxgroup class combobox contact continue datagrid default do double ds end else elseif Showloading screen skin slider static streaming strictfp string super switch synchronized table tabwidget textarea then this throw throws timer transient true enum extends false final finally float for form function gallery i18n if image imagestrip in implements repeat return richtext segui short widget window native net new null os package phone popup popupContextTable private protected kony As a general guideline, no variables should be declared resembling the kony.* namespace in order to avoid overriding of platform api's The keywords are reserved for a JavaScript project: abstract boolean byte char double false final float goto throw while implements instanceOf int interface long native null package private try with protected public short static synchronized throws transient true this typeof kony break case catch continue debugger default delete do else var finally for function if in instanceof new return switch void 7.4 Developing Mixed Mode Applications Kony Platform extends the capability to build applications with both native and HTML (web) forms. The web forms can be either statically bundled with the application or dynamically served from the server. The following table explains the characteristics of a native application: Characteristics Availability Is available as a natively deployable package (.app, .apk, or .cod) Copyright © 2012 Kony, Inc. All rights reserved. Page 98 of 785 Kony Studio User Guide - 2.1 Working with Applications Can be distributed through the app stores Utilizes the native widgets/layouts like the title bar, application menu, ListView, UITableView, Searchbar, native animations, Native SDK rendering engine Has access to native device functions like GPS, Camera, Contacts, Accelerometer, Mangnetometer, Encryption libraries (and thousands of other native SDK functions) UI elements/screens are packaged along with the application and network access done only for fetching business data Any application that meets the above criterion is a native application. 7.4.1 What is a Mixed Mode Application? Mixed Mode application is a version of the native application where some forms of the application are rendered in the WebView while others are rendered using the native SDK. You can choose the forms to be either native or web-based. The web-based forms can either be packaged statically along with the application or loaded from a URL. Characteristics Availability Is available as a natively deployable package (.app, .apk, or .cod) Can be distributed through the app stores Utilizes the native widgets/layouts like the title bar, application menu, ListView, UITableView, Searchbar, native animations, Native SDK rendering engine The forms which have the nature as native utilize the native widgets. Has access to native device functions like GPS, Camera, Contacts, Accelerometer, Mangnetometer, Encryption libraries (and thousands of other native SDK functions) UI elements/screens are packaged along with the application and network access done only for fetching business data If the nature of the web form is Dynamic then the screens are downloaded at runtime. 7.4.2 What is a Hybrid Application? A Hybrid application is a version of the native application where the entire layout rendering is done through the UIWebView (iPhone), WebView (Android) or BrowserField (BlackBerry) instead of the native SDK widgets. Characteristics Availability Is available as a natively deployable package (.app, .apk, or .cod) Can be distributed through the app stores Copyright © 2012 Kony, Inc. All rights reserved. Page 99 of 785 Working with Applications Kony Studio User Guide - 2.1 Utilizes the native widgets/layouts like the title bar, application menu, ListView, UITableView, Searchbar, native animations, Native SDK rendering engine Has access to native device functions like GPS, Camera, Contacts, Accelerometer, Mangnetometer, Encryption libraries (and thousands of other native SDK functions) UI elements/screens are packaged along with the application and network access done only for fetching business data If the nature of the web form is Dynamic then the screens are downloaded at runtime. All the forms are rendered using the UIWebView/WebView/BrowserField widget. 7.4.3 Kony Implementation for Mixed Mode and Hybrid Applications Kony Platform utilizes the Single Page Application (SPA) implementation for rendering the statically packaged forms in the Hybrid and Mixed Mode applications. In Hybrid mode, the application is an SPA running inside a native shell provided by the various native platforms. For dynamic forms, the traditional Mobile Web implementation is utilized. As illustrated in the above diagram, the Lua code is executed in the native context while the Java Script associated with web-based forms is executed in the browser widget context. The sharing of data between these contexts is done through 2 interfaces namely: hybrid.executeinspacontext("jsfunctionname",{paramlist}) This API helps to send the data from native execution context to browser widget context. Copyright © 2012 Kony, Inc. All rights reserved. Page 100 of 785 Working with Applications Kony Studio User Guide - 2.1 hybrid.executeinnativecontext("luafunctionname",{paramlist}) This API helps to send the data from browser widget execution context to native context. hybrid.executeintccontext("luafunctionname",{paramlist}) For native and static forms the context resides on the device but for dynamic forms, the execution context resides on the server. This API is used to exchange data with the server-side (Mobile Web) context. 7.4.4 Lua Modules Depending upon the application design, some of the Lua functions are invoked only from native context while others are invoked only from the browser widget context. It is difficult to differentiate these Lua functions at the design time. To overcome this, Kony Platform converts all the Lua modules to Java Script functions at the design time. This conversion is done while building a Mixed Mode or a Hybrid application, but not for a native application. The following diagram explains the representation of the forms and Lua modules at design time and run time. Copyright © 2012 Kony, Inc. All rights reserved. Page 101 of 785 Working with Applications Kony Studio User Guide - 2.1 7.4.5 Design Guidelines for a Mixed Mode Application Each of the context (native, browser widget, or server runtime) stores the UI model, global variables, function definitions associated with it. For example, the native forms (data and definition) are stored in native context while static forms (web-based) are stored in the browser widget context. A seamless sharing and synchronization of these states across these contexts involves very complex engineering and can lead to performance issues as the application size grows. The recommended approach is to have an entire functional module to be a web-based or native module. For example, the forms in payments module can be marked as Static HTML5, while the forms in Remote Check Deposit module can be marked as Native. These modules should be independent pieces of functionality and have clear entry and exit points. Kony Studio provides the capability to mark a form as native or web-based by changing the nature of the form. If the code is not modularized accordingly, it can lead to major re-factoring of the code. Note: An application which has been designed for Mixed Mode implementation can be easily changed to native, as the Mixed Mode APIs are available to both the native and browser widget context. So, invoking the function hybrid.executeinspacontext will not result in an error as it would execute the corresponding Lua function. 7.4.6 Set the Form Nature A form can be rendered using native components or the browser widget depending on the nature of the form. Copyright © 2012 Kony, Inc. All rights reserved. Page 102 of 785 Working with Applications Kony Studio User Guide - 2.1 For more information about changing the nature of the form, see Set Nature. Native Indicates that form will be rendered in the native context using the native layout and components. HTML5 Static Indicates that the form will be rendered using the browser widget (UIWebView on iPhone, WebView on Android, and BrowserField on Blackberry). The static nature also means that all the HTML/JS/CSS required for the form will be packaged statically (during build time) along with the deployable binary. HTML5 Dynamic Indicates that the form will be rendered using the browser widget (UIWebView on iPhone, WebView on Android, and BrowserField on Blackberry). But, unlike the static nature, the HTML/CSS/JS will be downloaded at runtime instead of being packaged along with the application binary. 7.4.7 Data Exchange between Native Form and Web Form The methods in the Mixed Mode namespace/package are used to exchange data between the native and the web context. Here is an example to see how this interaction works. In the below scenario, let us assume that the user credentials are captured in the login form (Native form). The Lua module authenticates the user and displays the account summary form (HTML5 Static form). Copyright © 2012 Kony, Inc. All rights reserved. Page 103 of 785 Working with Applications Kony Studio User Guide - 2.1 7.4.8 Invoke Native Device Features from Web Form The native device features or APIs can be executed only in the native context. To access them from the browser widget context, use the flow as illustrated in the below diagram. Copyright © 2012 Kony, Inc. All rights reserved. Page 104 of 785 Working with Applications Kony Studio User Guide - 2.1 7.5 Creating an Application You can create applications or work on the existing applications. Depending on the tasks for which it is designed or developed, an application can perform various operations. You can create applications related to any business vertical using the IDE. Currently the Kony Applications relate to the following Industry Verticals: l Airlines l Auto Rentals l Hotels l Insurance l Banking l Investments l Automotive l Retail/Commerce l Media You can create other types of applications as well. Copyright © 2012 Kony, Inc. All rights reserved. Page 105 of 785 Working with Applications Kony Studio User Guide - 2.1 To create an application, follow these steps: Important: l l l Lua projects can only be created in 32-bit IDE. While creating SPA and Server Side Mobile Web applications, ensure to enable Accept Cookies option on the device browser. Consider the limitations while developing the Mobile Web in JavaScript language: o Development is only supported in HTTP Session Manager (middleware without memcache). o Require middleware 5.0.11 or above GA plug-in. Note: If you are using an old middleware, you must copy the js.jar from the 5.0.11 middleware plug-in to middleware lib folder on the middleware server. 1. Launch Eclipse. 2. Open Kony Perspective. 3. Right-click in the Applications view area. 4. Select New Application from the context menu. New Kony Application window appears as shown below: 5. Enter a name in the Application name field. Copyright © 2012 Kony, Inc. All rights reserved. Page 106 of 785 Kony Studio User Guide - 2.1 Working with Applications 6. Chose Project Type as Lua or JavaScript and click Finish. Note: l We recommend to name the workspace in Camel Case (capitalize the first letter of every word). l Do not use any spaces or special characters while naming the application name. The new application generates empty folders for forms, popups, modules, resources, and services by default. Note: The IDE provides a set of Kony default skins that give a uniform look for all the widgets across platforms. All these default skins are available in the Skin View. If required, you can change the skins for widgets. You can see the Kony default skins in the Application Themes window and also in the Skin View as shown below: Application Themes window Skin View Alternate Procedure Copyright © 2012 Kony, Inc. All rights reserved. Page 107 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Launch Eclipse. 2. Open Kony Perspective. 3. Select File -> New -> Kony Application. 4. Enter a name in the Application name field 5. Chose Project Type as Lua or JavaScript and click Finish. The new application generates forms, popups, modules, resources, and services by default. 7.6 Adding Forms to an Application Form is a visual area (basic application screen) that holds other widgets on it. Form is the starting point for any application. A form is the top most container. A form can contain any number of widgets but cannot contain another form. The Form starts laying out the first level child widgets one by one. Each widget occupies the same width as that of the form and the height is determined by the preferred height property of the widget. For more information about how a form lays out its widgets, see Kony Widget User Guide. As the screen resolution varies between a mobile and a tablet, Kony Studio provides you the ability to add forms for both mobile and tablet channels separately. You can use the same form for both mobile and tablet or design separate forms based on your requirement. Note: l l You cannot perform any action on an empty form (form without any widgets on it). To prevent erratic behavior of the application, we recommend that you do not use empty forms. On iPad, Android, and Windows Mobile platforms, the same form can be configured to support both portrait and landscape orientations. For more information about the platform specific property that supports orientations, see Kony Studio Widget Guide. Important: Limitation in creating forms for Server Side Mobile Web applications - Expected behavior - the appmenu must dock at the end of the screen irrespective of the form size. But, while running on a Basic, BJS, and Non-touch devices, if the form size is small, the appmenu gets docked just at the end of the form, which results in a gap between the end of the screen and the appmenu. Copyright © 2012 Kony, Inc. All rights reserved. Page 108 of 785 Working with Applications Kony Studio User Guide - 2.1 While naming the forms in an application, we recommend you to prefix every form name with frm followed by a logical name in Camel Case. For example, if you are creating a form that displays search results, name it as frmSearchResults. 7.6.1 Form Lifecycle A Form is a top level container that allows you to place the required artifacts and design the application screens. Form allows you to add other containers and widgets to create a widget hierarchy. A Form fills the device screen provided for an application (excluding the device level screen controls like status bar). Form stacking Typically a Form is shown by a user action on another Form. That means the navigation between Forms happen by the events on another Form. All these navigation's are pushed into the stack to track the navigation path, so that user can navigate back to the previous Forms in the exact reverse order of its forward navigation. Navigation to a Form that is already visited and available in the middle of the stack, that Form is brought back to the top of the stack by popping all the above Forms out of the stack. Currently this stack is not exposed directly to the developers and In future there will be APIs around manipulating this stack directly. Lifecycle Methods A Form is defined to have a lifecycle method that gets called at appropriate events. These events will allow you to manage the application for better handling of resources. The following are the lifecycle methods of a Form: addWidgets - this is called when the Form is used for first time either l for accessing its widgets or l accessing its properties or l the Form is shown through show method or when any other method on the Form is invoked. For example, Any of the below can trigger the addWidgets life cycle method of form1 if form1 is not yet initialized. l form1.label1 l form1.title l form1.show() init - this is called immediately after addWidgets event for any initializations required for this Form. It is basically used to initialize the form and any widgets. In case of Mobile Web and SPA, addWidgets and init events gets called as soon as the Form is created and in case of native platforms, as an optimization, these events are deferred till the first access. Copyright © 2012 Kony, Inc. All rights reserved. Page 109 of 785 Working with Applications Kony Studio User Guide - 2.1 preShow - this is called just before it is visible on the screen. Form can be made visible by explicitly calling the show method of the form. postShow - this is called immediately after a Form is visible on the screen. Form can be made visible by explicitly calling the show method of the form. onHide - this is called when Form goes out of the screen. A Form can go out of the screen when another Form is trying to be shown. onDestroy - this is called when a Form is destroyed. Destruction of the Form happens when the developer explicitly calls destroy and this event gets called before really destroying the Form. The following image illustrate the lifecycle of a Form: For more information about these events, see Kony Widget User Guide. For more information about form.destroy API, see Kony API Reference Guide. 7.6.2 Form Types Forms in an application are of two types: Copyright © 2012 Kony, Inc. All rights reserved. Page 110 of 785 Kony Studio User Guide - 2.1 Working with Applications l native l web-based o Static o Dynamic. The characteristics of each form type is listed in the following table: Form Type Characteristics Rendering engine used to display form UI definition (the widget layout and skins) UI logic (logic that alters the user experience based on business rules) Business Data Native Static Web-based Dynamic Native SDK UIWebView UIWebView packaged along with the application packaged along with downloaded from the the application server packaged along with the application packaged along with downloaded from the the application server downloaded from the server downloaded from the server downloaded from the server 7.6.3 Set Nature To set the nature of a form, follow these steps: Important: You can set the nature only for a mobile form. 1. Navigate to the Applications View. 2. Expand the forms folder within the required application. 3. Select the required form, right-click and select Set Nature. Select the appropriate option based on your requirement. The current nature of the form is marked with a tick mark against it. Copyright © 2012 Kony, Inc. All rights reserved. Page 111 of 785 Working with Applications Kony Studio User Guide - 2.1 7.6.4 Adding Forms for Mobile To add forms to an application for mobile, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand forms and right-click mobile -> New Form. 4. New Form window appears. 5. Enter a name for the form in Name field and click Finish. New form is created. The newly created form appears under forms folder. 6. Right-click any form and select Mark as Start Up to mark that form as the start up form in the application. The start up form appears in bold under forms and it will be the first form to be displayed when you run the application on a mobile channel. Note: The IDE marks the first form created in the application as the Start Up form. If you want to change the Start Up form, use this option and change it. Note: All the forms that you create should have unique names across the application. 7.6.5 Adding Forms for Tablet Important: Do not copy the forms used for mobile (available under forms -> mobile) to tablet. If there is a scenario where you must copy the forms from mobile folder to tablet folder, follow this procedure: 1. Copy the required forms from mobile folder to tablet folder using Windows Explorer. 2. Navigate to <workspace>/<project>/forms/tablet folder from Windows Explorer. 3. Open the form file (.kl file) in a text editor like Notepad, WordPad, and so on. 4. Search for <formCategory> and change its value from 0 to 100. 5. Save the .kl file and close it. 6. Refresh the tablet folder located under <project>/forms in the IDE. To add forms to an application for tablet, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand forms and right-click tablet -> New Form. 4. New Form window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 112 of 785 Working with Applications Kony Studio User Guide - 2.1 5. Enter a name for the form in Name field and click Finish. New form is created. The newly created form appears under forms folder. 6. Right-click any form and select Mark as Start Up to mark that form as the start up form in the application. The start up form appears in bold under forms and it will be the first form to be displayed when you run the application on a tablet channel. Note: The IDE marks the first form created in the application as the Start Up form. If you want to change the Start Up form, use this option and change it. Note: All the forms that you create should have unique names across the application. 7.6.6 Adding Forms for Desktop The Desktop channel uses a set of forms that are created under the desktop category. Because of the dimensions of the desktop, you must design forms and place widgets on those forms keeping in view the size of the desktop. The Desktop channel does not support some of the widgets. For more information about the list of widgets that are supported on this platform, see Kony Widget User Guide. The Desktop channel indicates the Windows desktop. To add forms to an application for desktop, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand forms and right-click desktop -> New Form. 4. New Form window appears. 5. Enter a name for the form in Name field and click Finish. New form is created. The newly created form appears under forms folder. 6. Right-click any form and select Mark as Start Up to mark that form as the start up form in the application. The start up form appears in bold under forms and it will be the first form to be displayed when you run the application on a desktop_kiosk channel. Note: The IDE marks the first form created in the application as the Start Up form. If you want to change the Start Up form, use this option and change it. Note: All the forms that you create should have unique names across the application. 7.7 Adding Popups to an Application A popup is a visual component that holds other widgets on it. For more information about the widgets that can be added to a popup, see Kony Widget User Guide. Copyright © 2012 Kony, Inc. All rights reserved. Page 113 of 785 Working with Applications Kony Studio User Guide - 2.1 A popup usually appears in the center of the screen on top of the form from which you have invoked the popup. It does not span the entire screen width. Popups allow you to partition UI design into smaller parts. As the screen resolution for a mobile varies between a mobile and a tablet, Kony Studio provides you the ability to add popups for both mobile and tablet channels separately. You can use the same form for both mobile and tablet or design separate popups based on your requirement. Typically, you can use popups instead of forms for: l the user authentication details screen l general data entry l advertisements l alerts to the user that require some user input l display of additional information without navigating away from the current form While naming the popups in an application, we recommend you to prefix every popup name with pop followed by a logical name in Camel Case. For example, if you are creating a popup that displays Terms And Conditions, name it as popTermsAndConditions. Important: If you have marked all the forms to be submitted through a secure protocol, then any popup must also be secured. To make a popup secured, you must set the SecureSubmit property of a popup to true. For more information, see Kony Widget User Guide. To add popups to an application for mobile, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand popups, right-click mobile and select New Popup. Copyright © 2012 Kony, Inc. All rights reserved. Page 114 of 785 Working with Applications Kony Studio User Guide - 2.1 4. New Form window appears as shown below: 5. Enter a name for the popup in Name field and click Finish. New popup is created. The newly created popup appears under popups as shown below: Note: All the popups that you create for mobile should have unique names. To add popups to an application for tablet, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. Copyright © 2012 Kony, Inc. All rights reserved. Page 115 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Expand popups, right-click tablet and select New Popup. 4. New Form window appears as shown below: 5. Enter a name for the popup in Name field and click Finish. New popup is created. The newly created popup appears under popups as shown below: Note: All the popups that you create for tablet should have unique names. Copyright © 2012 Kony, Inc. All rights reserved. Page 116 of 785 Kony Studio User Guide - 2.1 Working with Applications Important: The popup names used for mobile channel can be used for tablet channel and vice versa. Based on the screen resolution, the application uses only one set of forms (mobile or tablet related) while running on the device. 7.8 Adding Widgets to a Form The widgets in the IDE are small chunks of code that are re-used without additional compilation. The widgets are represented as visual components in the IDE. Some widgets support interaction with the user (for example: Button, CheckBoxGroup, RadioButtonGroup and so on). Others act as containers and group the widgets that are placed in them (for example: Form). The widgets added to forms define the application screens. The widgets appear on the application screens as they are laid out on the forms. 7.8.1 Naming Conventions Kony Studio auto-generates the ID for every widget you place on a form/popup. Do not retain those IDs. Change the ID of each widget to be meaningful and logical. We recommend you to use the following naming convention: <designatedPrefix><WidgetName> prefix specified for each widget followed by a logical name in Camel Case. For example, to modify the IDE of a button that searches files on the machine, name it as btnSearchFiles. We recommend you to use the prefixes specified below for the widgets while naming them: Widget HBox VBox TabPane Tab Label Button Browser TextBox TextArea Calendar ComboBox ListBox CheckBoxGroup RadioButtonGroup Link Line Image Prefix hbx vbx tbp tab lbl btn brws txt txa cal cmb lst chk rbt lnk lin img Copyright © 2012 Kony, Inc. All rights reserved. Page 117 of 785 Kony Studio User Guide - 2.1 Working with Applications Widget MenuItem Segment ImageGallery HorizontalImageStrip Phone Camera Switch PickerView Prefix mnu seg igl his phn cam swt pkv To add widgets to a form, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand forms. 4. Double-click the form to which you want to add widgets. The selected form opens. 5. Go to expanded Palette. 6. Drag and drop the widgets on to the form. For more information about widgets and their behavior, see Widgets. For more information about widget properties, see Kony Widget User Guide. 7.9 Configuring Widget Properties The widget properties determine the behavior of a widget. A widget's behavior varies based on the properties set for it. You can configure the widget properties in the Properties view within the IDE. For more information about configuring widget properties, see Kony Widget User Guide. You can also set the widget properties from the code. For more information about setting the widget properties from code, see Kony Widget User Guide. To configure widget properties, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand forms. 4. Double-click any form to open it. 5. Click any widget on the form to select the widget. Once the widget is selected, its properties appear in the Properties view as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 118 of 785 Working with Applications Kony Studio User Guide - 2.1 Alternatively, you can also select the widget in the Outline view to see its properties. 6. Set the values for different properties in the Properties view. For more information about widget properties, see Kony Widget User Guide. 7.10 Applying Grid Layout Kony Platform allows you to divide any container widget except ScrollBox, such as forms or HBoxes into multiple columns and rows. This feature enables you to place widgets on a form without having to use multiple HBoxes or VBoxes. All widgets when placed inside the grid cell, will occupy 100% of the cell space. The margins & paddings provided to widget are applied with in this area. If a developer places a widget in a cell and overrides it by placing another widget in the same cell, the behaviour is undefined. It is developer's reponsibility to remove the previously placed widget and then place a new widget into the cell. The Grid Layout can only be applied to a form for Desktop Web and Windows 8. To apply a Grid Layout to a Container Widget, follow these steps: 1. Go to Applications view. 2. Expand the application in which you want to use the Grid Template. 3. Do any of the following: l To apply Grid Layout for a form in Desktop Web, navigate to forms > desktop, right-click desktop and select New Form. The Create a New Form window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 119 of 785 Kony Studio User Guide - 2.1 Working with Applications l To apply Grid Layout for a form for a Windows 8 tablet, navigate to forms > tablet, right-click tablet and select New Form. The Create a New Form window appears. 4. Enter a name for the Form and click Finish. A new form is created. 5. Right-click the widget and select Apply GridLayout. The container widget is by default divided into a 4x4 grid. 6. To divide a container widget within a form again, you can drag and drop other container widgets to the cell in the grid and repeat steps 1 and 2. 7. Right-click the widget to which the layout is applied and select Layout Properties. The Grid Layout View Appears. You can also navigate to Grid Layout by navigating to the Window>Show View>Other..Grid Layout View. 8. In the value columns of the Grid Layout View, you can set the number of rows and columns the grid contains. 9. You can change the width of a column by selecting the button in the Column Width value field. 10. Enter the required value in the respective columns. The sum of the column widths should be 100. 11. Click OK. 12. After you drag and drop a widget in a cell in a grid, to set the number of rows and columns the widget occupies : i. Select the widget. ii. In the Grid Layout View, enter a value in the Column Span and Row Span fields. The value entered in the Column Span field specifies the number of columns the widget occupies from the current column. The value entered in the Row Span field specifies the number of rows the widget occupies from the current row. For example, if the widget is in the third row and you set the column span as two, the widget occupies rows 3 and 4. Copyright © 2012 Kony, Inc. All rights reserved. Page 120 of 785 Working with Applications Kony Studio User Guide - 2.1 If you try spanning a widget across rows in which widgets already exist, the widgets in those rows will be overlapped and replaced. iii. The Row No and Column No field specify the row and the column the widget is in. You can either drag and drop the widget on the form to a specific cell in the grid or you can specify the row number and the column number in the grid where you want the widget to be placed. 13. To return to a form without any grids, right-click the form and select Apply XYLayout. 7.11 Importing Custom Widgets Kony Studio now enables you to import, manage, and use third-party widgets available from other libraries and frameworks. You can also create your own custom widgets by importing css and js files associated with the widget. This enables the user to use other widgets developed on other platforms and not just be restricted by the widgets provided in Kony Studio. When you import a custom widget, ensure that you copy the associated css and js files as well. This feature is only applicable for SPA applications. Note: The developer has to ensure that the custom widget library developed takes care of the individual browser implementations on various SPA supported browsers. 7.11.1 Important Considerations Kony platform has defined a contract that any custom widget should implement. This contract is referred to as a widget wrapper. The main purpose of the widget wrapper is to enable Kony One platform to initialize the widget when it is placed in a form that is currently being rendered. The wrapper notifies the custom widget when there is a change in its state. The change in state can be a programmatic change to one of the properties exposed by it or a user driven event raised on the custom widget. All such changes are notified to the custom widget through the widget wrapper contract (modelChange). The developer of the custom widget and its wrapper can make use of the information provided in the modelChange call and make changes to the custom widget state accordingly. If you want to use a widget developed by using any 3rd party library or framework, you should expose the widget to the Kony SPA platform by implementing an interface defined in JavaScript. These *.js files are imported using the Importing Custom Widgets procedure. The contract definition is as follows: //Using this function you initialize the widget. A parentNode is a container where you place the custom widget. It is the placeholder div that respects the layout of a Kony Widget and the custom widget is placed in the parentNode. The widgetModel parameter is a hashmap containing key-value pairs of the properties and its corresponding values. function initializeWidget (parentNode, widgetModel) Copyright © 2012 Kony, Inc. All rights reserved. Page 121 of 785 Working with Applications Kony Studio User Guide - 2.1 //Using the modelChange function any changes to the widget property is mapped both in Kony widget model and the third party widget property. The widgetModel is a hash map containing key-value pairs of the properties and its corresponding values. propertyChanged is the key of the property being changed. propertyValue is the value assigned to the key. function modelChange(widgetModel, propertyChanged, propertyValue) 7.11.1.1 Sample wrapper *.js file //Ensure the name of the class is the same as that of the widget name specified through IDE datepicker = { datePicker: null, /** * widgetModel : id, containerWeight,margins, paddings, contentAlignment * * */ //Initialize widget is invoked by SPA for widget initialization using the constructor initializeWidget : function(parentNode, widgetModel) { var calTextbox = '<input type="text" id="'+widgetModel['id']+'" style="border:1px solid #444444; width:100%;">'; parentNode.innerHTML = calTextbox; widgetModel["date"] = null; var calTextbox = document.getElementById(widgetModel['id']); //Sencha widget constructor datepicker.datePicker = new Ext.DatePicker({useTitles:true}); datepicker.datePicker.on('change', function(me, date) { var dt = date.getDate(); dt = (dt<10) ? '0'+dt : dt; var mth = date.getMonth() + 1; mth = (mth<10) ? '0'+mth : mth; var viewDateStr = dt + '/' + mth + '/' + date.getFullYear(); datepicker.modelChange(widgetModel, "date", viewDateStr); }); calTextbox.onfocus = function(e) { this.blur(); datepicker.datePicker.show(); }; }, modelChange : function(widgetModel, propertyChanged, propertyValue) { Copyright © 2012 Kony, Inc. All rights reserved. Page 122 of 785 Working with Applications Kony Studio User Guide - 2.1 if (propertyChanged === "date") { widgetModel["date"] = propertyValue; var calTextbox = document.getElementById(widgetModel['id']); var dateArr = propertyValue.split('/'); var dt = parseInt(dateArr[0], 10); dt = (dt<10) ? '0'+dt : dt; var mth = parseInt(dateArr[1], 10); mth = (mth<10) ? '0'+mth : mth; var yr = parseInt(dateArr[2], 10); var viewDateStr = dt + '/' + mth + '/' + yr; calTextbox.value = viewDateStr; datepicker.datePicker.setValue(new Date(yr, mth-1, dt), false); } } } Important: If you specify an absolute value for a property in the library files, the widgets placed next to it or after it might be distorted so its recommended not to provide an absolute value. Important: Third-party container custom widgets such as, tab panes are not supported. 7.11.2 Importing Custom Widgets To import files for a third-party widget, execute the following: 1. In the Application view, right click an application and select Import > Import Files. 2. In the From directory field, browse for the folder where the library files of the widget are located. Note: Ensure all the library files(css and js files)are in a folder before you begin importing. If the custom widget library has its own folder structure, copy the folder structure as is into another folder. Copyright © 2012 Kony, Inc. All rights reserved. Page 123 of 785 Working with Applications Kony Studio User Guide - 2.1 3. In the Into folder field, browse to the <<applicationname>>/resources/thirdpartywidgets folder. The library folder must be present in the thirdpartywidgets folder or the custom widget will not be imported. Note: If you have a wrapper js file for the custom widget, import it into the <<applicationname>>/resources/thirdpartywidgets/widgetwrapper folder using steps 1 to 3. Copyright © 2012 Kony, Inc. All rights reserved. Page 124 of 785 Working with Applications Kony Studio User Guide - 2.1 4. Click OK and click Finish. Alternate Procedure to import library files 1. In the Application view, expand the application. Navigate to resources. 2. Expand resources. 3. Go to the Navigator View. 4. To create a folder where the library files are copied , execute the following: a. Right-click the thirdpartywidgets folder. b. Select New > Other. The Select a wizard dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 125 of 785 Working with Applications Kony Studio User Guide - 2.1 c. Expand General. Select Folder and click Next. The Create a new folder resource dialog appears. The parent folder will always be thirdpartywidgets folder of the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 126 of 785 Working with Applications Kony Studio User Guide - 2.1 d. In the Folder name field, enter the name of the folder in which the third party widget libraries will be copied. e. Click Finish. 5. Go back to the Applications View. 6. Right-click and select Refresh. 7. Right click the created folder under resources and select Import > Import Files 8. In the From directory field, browse for the location of the library files of the custom widget. 9. In the Into folder field, browse to the <<applicationname>>/resources/thirdpartywidgets/<<created folder name>> folder. The library folder must be present in the thirdpartywidgets folder or the custom widget will not be imported. Note: If you have a wrapper js file for the custom widget, import it into the <<applicationname>>/resources/thirdpartywidgets/widgetwrapper folder using steps 7 to 9. 10. Click OK and click Finish. After importing the library files of the custom widget, execute the following: Copyright © 2012 Kony, Inc. All rights reserved. Page 127 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Navigate to the Applications View, right click and select Refresh. 2. In the Application view, right click an application and select Integrate Third Party > Manage Custom Widgets. The Manage Custom Widget Libraries dialog appears. 3. Click New to add a new custom widget. The Add New Library dialog appears. 4. Enter the name of the library folder imported. An error occurs if you have not imported the widget library or have entered an incorrect name. Copyright © 2012 Kony, Inc. All rights reserved. Page 128 of 785 Working with Applications Kony Studio User Guide - 2.1 5. Click OK and click Next. The Manage Custom Widgets dialog appears. 6. Click to add a widget name and its corresponding widget library and click Next. The Add Custom Widget dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 129 of 785 Working with Applications Kony Studio User Guide - 2.1 7. In the Name field, add the name for the custom widget. Important: Ensure the widget name you specify is the same as the function specified in the wrapper file. 8. From the Select Library drop-down list, select the library you want to import. This field is populated only if you have imported library and added it using step 7-8. Once you have selected the library, all its files are populated under the SPA Selected Files area. Copyright © 2012 Kony, Inc. All rights reserved. Page 130 of 785 Working with Applications Kony Studio User Guide - 2.1 9. Select the checkbox next to the files you want to import for the widget. The *.js files contain the information about the functional aspects of the widget, such as the methods and events associated with the widget. The *.css files contain styles that define how the widget appears. Using the up or down arrows in the SPA Selected Files area, you can select a file and set the order in which the files are loaded and executed. 10. In the Widget Property area, you can: l l View the default properties defined for the widget in the Default Property tab. When custom widgets are used in an application, the Kony SPA channels provide a pre-defined area ( defined by the container weight of the widget) with in which the widget can render itself. The pre-defined default properties defined are as follows: o ID - widget ID o Visibility - visibility of the widget. The platform uses this to make a widget visible or invisible based on values provided by the developer. o Margins - This is applied by the platform to the container area provided to the custom widget o Paddings - This is applied by the platform to the container area provided to the custom widget. o Skin - This again applied to the container area provided to the custom widget by the platform. The developer while importing the custom widget can define his own properties specific which are displayed by the IDE in the Property Palette against the widget .Add platform specific Copyright © 2012 Kony, Inc. All rights reserved. Page 131 of 785 Working with Applications Kony Studio User Guide - 2.1 properties for the custom widget. After specifying a property name, specify the datatype for that property in the Value Type field. The Value type can be String, Date, Number, Boolean, List, or Event. Specify a default value for the defined property. Note: If you select the Value Type as List, click the button in the Default Value column. In the subsequent dialog that appears, define the values to be displayed in the list. You can reorder the list using the up or down arrows. Note: The developer can also specify any events that are exposed by the custom widget. The event is handled by the third party widget. 11. In the Select files specific to Custom Widget area, click the custom widget. to add the imported wrapper classes for 12. The Select Library dialog appears. All the files present within the <workspacename>><applicationname> folder are visible when you search for the library name. 13. Select a file and click to delete a file. Select a file and use the up or down arrows to reorder the sequence in which the wrapper files are loaded and executed. 14. Click OK and then click Finish. 15. You can view the newly added Widget under Custom Widgets in the Palette. Copyright © 2012 Kony, Inc. All rights reserved. Page 132 of 785 Working with Applications Kony Studio User Guide - 2.1 All the Default and SPA Specific properties defined for the Custom widget can be viewed in the Properties View. For more information about adding the widget to a form, refer Adding Widgets to a Form. The Preview feature is not available for custom widgets. After you build the application you can view the library files which are built in the ....webapps/<appname>/platform/jslib/thirdparty/widgets folder. You can perform the following additional operations on the Manage Custom Widget Libraries dialog: l Add additional Libraries by clicking the Add button. l Remove defined Libraries by clicking the Remove button. l Click the Up or Down buttons to change the order of the libraries. You can perform the following additional operations on the Manage Custom Widgets dialog: Copyright © 2012 Kony, Inc. All rights reserved. Page 133 of 785 Kony Studio User Guide - 2.1 Working with Applications l Add additional widgets by clicking . l Remove defined widgets by selecting a widget name and clicking l Edit defined widgets by selecting the widget and clicking . . Important: If you edit the properties of a defined custom widget after you drag and drop it on a form, ensure that you delete the added instances of the custom widget on the form and add it on the form again. Since the custom widgets added on the form before the edit will not reflect the newly changed properties. 7.12 Comparing and Replacing Forms 7.12.1 Comparing Different Versions of a Form The compare forms feature enables you to compare a form with its prior saved versions. The prior saved versions are saved in the Local History. Using the Compare With option, you can compare the version using the Tree view and the Graphical View. For more information on replacing forms, refer the Subversion Eclipse Help To change the Local History settings: Copyright © 2012 Kony, Inc. All rights reserved. Page 134 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Open Kony Studio and navigate to Window > Preferences. The Preferences dialog appears. 2. In the left panel, navigate to General>Workspace>Local History. The Local History settings appear in the right panel. 3. Enter the required values in the fields and click OK. Important: Ensure that you set the minimum value as 10 MB since most form files are above 2MB and if you set a lesser value the Local History of the form is not retained. To compare forms using the Compare Editor: 1. Go to Applications view. 2. Right-click on a form that you would like to compare and select Compare With > Local History. Copyright © 2012 Kony, Inc. All rights reserved. Page 135 of 785 Working with Applications Kony Studio User Guide - 2.1 3. The History View appears as a tab beside the Emulator View. 4. Execute any one of the following actions to compare a form: l l l Click the Compare Mode( ) icon and double-click a form from the History View that you want to compare the current form to. Right-click a form in the History View and select Compare with Each Other. Select any two forms from the History View ( by holding down the Ctrl key). Right -click and select Compare with Each Other. The Compare Editor appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 136 of 785 Working with Applications Kony Studio User Guide - 2.1 7.12.2 Comparing Repository Forms This section comprises the procedures on how to compare forms in SVN and states the usage of the Compare Editor. You can compare forms in the repository (SVN) with any of the following: l l Base revision: Enables you to compare a form to the last revision of the form you have checked out from the repository. Latest from Repository: Enables you to compare a form with the latest version of the form available in the repository. l Revision: Enables you to compare a form with any revision of a form available on svn. l Branch/Tag: Enables you to compare a form with a previous Branch or Tag. l Local History: Enables you to compare a form with a version saved in Local History. To compare an SVN form with another form (in the local history/base revision/ or latest from repository) execute the following: 1. Go to Applications view. 2. Right-click on an SVN form that you would like to compare and select Compare With > Base Revision/ Latest from Repository/ Local History. Copyright © 2012 Kony, Inc. All rights reserved. Page 137 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Based in your selection, the following events occur: 1. If you select Base Revision, the Compare Editor appears. 2. If you select Latest from Repository, the Compare Editor appears. 3. When you select the Local History, you perform the following additional steps to launch the Compare Editor: Copyright © 2012 Kony, Inc. All rights reserved. Page 138 of 785 Working with Applications Kony Studio User Guide - 2.1 i. The History View appears as a tab beside the Emulator View. ii. For viewing the Local History, execute any one of the following actions to compare a form: a. Click the Compare Mode( ) icon and double-click a form from the History View that you want to compare the current form to. b. Right-click a form in the History View and select Compare with Each Other c. Select any two forms from the History View ( by holding down the Ctrl key). Right -click and select Compare with Each Other. The Compare Editor Copyright © 2012 Kony, Inc. All rights reserved. Page 139 of 785 Kony Studio User Guide - 2.1 Working with Applications appears: To compare an SVN form with another form revision in SVN, execute the following: Copyright © 2012 Kony, Inc. All rights reserved. Page 140 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications view. 2. Right-click on a form that you would like to compare and select Compare With > Revision. The Compare workspace form and versions Editor appears. The version in bold represents the version you are currently on. Copyright © 2012 Kony, Inc. All rights reserved. Page 141 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Double-click on any other version to launch the Compare Editor. To compare an SVN form with another form on a different branch/tag, execute the following: Copyright © 2012 Kony, Inc. All rights reserved. Page 142 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications view. 2. Right-click on a form that you would like to compare and select Compare With > Branch/Tag. The Compare with Branch/Tag dialog appears. 3. In the Compare to field, set the URL of the branch you want to compare your current form to and do any one of the following: i. Select the Compare with Head Revision checkbox to compare the form with a form from the latest revision. Copyright © 2012 Kony, Inc. All rights reserved. Page 143 of 785 Working with Applications Kony Studio User Guide - 2.1 ii. Deselect the Compare with Head Revision checkbox, the Revision Field is enabled. Click the Select button. Select a Revision from the Resource History dialog and click OK. 4. Set Compare Type as Graphical in the Branch/Tag dialog and click OK. The Compare Editor appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 144 of 785 Working with Applications Kony Studio User Guide - 2.1 7.12.3 Resolving a Conflict If you have not updated a form and have started implementing changes in it, when you save the form and try to commit the form, you might face a conflict. If there is a conflict, execute the following: 1. Right-click the form which is conflicted and navigate to Team > Synchronize with Repository. 2. A Synchronize tab appears which shows the conflict. 3. Navigate to the conflicted form. 4. Right-click on the form and select Override and Update. A confirmation message appears stating that all the local changes will be discarded. All the changes that have been made locally are saved in the Local History when you save the form. Important: Ensure that you set the minimum value as 10 MB for the Local History. Since most form files are above 2MB and if you set a lesser value the Local History of the form is not retained. For more information on setting the Local History, refer to Comparing Forms. 5. Click Yes. 6. Navigate back to the Kony Perspective. 7. Right- click on the form and navigate to Compare With > Local History.The History View appears as a tab beside the Emulator View. Copyright © 2012 Kony, Inc. All rights reserved. Page 145 of 785 Working with Applications Kony Studio User Guide - 2.1 8. For viewing the Local History of the SVN form, execute any one of the following actions to compare a form (The form in bold represents the current form(updated and overridden with the form in svn, select any form except the first form to compare): a. Click the Compare Mode( ) icon and double-click a form from the History View that you want to compare the current form to. b. Right-click a form in the History View and select Compare with Each Other Copyright © 2012 Kony, Inc. All rights reserved. Page 146 of 785 Working with Applications Kony Studio User Guide - 2.1 c. Select any two forms from the History View ( by holding down the Ctrl key). Right -click and select Compare with Each Other. The Compare Editor appears: 7.12.4 Comparison Settings You can perform any of the following operations using the Compare Settings area: l l l Compare Modes: Using the Compare feature you can compare the forms using any one of the following modes: o Default Mode: Provides the Tree View and Graphical View for form comparison. o Compare Form Files: Provides a Tree and Graphical comparison of the forms. o Text Compare: Provides a text comparison of the forms. Save: (Disabled) Saves the changed form. This property is enabled only when you port a widget or properties from one form version to another. Save As: Enables you to save the merged forms. When you click the Save As icon, the Save Merged Form dialog appears. The form on the left side is saved by default. To save the form on the right, select the Save Right Form checkbox. Copyright © 2012 Kony, Inc. All rights reserved. Page 147 of 785 Working with Applications l l l Kony Studio User Guide - 2.1 Clear and Reload Model: Discards all the changes made to the forms in either sides and reloads them in the Comparison Editor. Toggle View: Enables you to toggle between the Tree View, Graph View, and the Default View. Link Left and Right View: Enables you to relate the widgets between the two forms. For example if a button is present on version 1 and not present on version 2, when you click on the button on version1 in the Tree View or Graphical View, the corresponding missing button is highlighted in version 2. Similarly if you copy a widget or a property from the left form to the right form or from the right form to the left form and enable the Link Left Right View, whenever you click that particular property or widget in one form the corresponding widget or property is highlighted in the other form. Note: The Link Left and Right View or vice versa works only for widgets having the same ID on both forms. 7.12.5 Filter Area Enables you to view only those widgets in the Tree View whose filter values are entered in the Filter Area. This property is useful when you have multiple widgets on the form and you want to edit properties of only certain widgets or edit certain properties of all the widgets. The Filter Area enables you to filter the following: l l l l l Widget: Enables you to view a certain widget in the Tree View. Only the widget entered in the Widget field is displayed in the Tree View. Category: Enables you to view the categories of widgets in the Tree View. Only the category entered is displayed in the Tree View. The widgets properties are categorized by their General properties, Appearance, Events, and the Platform names. Property: Enables you to view the properties of widgets in the Tree View. Only the property entered is displayed in the Tree View. The widget properties are the common properties and the platform specific properties of a widget. Hide Properties: Enables you to hide the properties of widgets in the Tree View. Whole Word: Enables you to search the widget or property by the entire keyword entered in the Widget/Category/Property field. Copyright © 2012 Kony, Inc. All rights reserved. Page 148 of 785 Working with Applications Kony Studio User Guide - 2.1 7.12.6 Tree View The Tree View represents a hierarchical view of widgets and properties for each of the forms. The Tree View enables you to compare widgets of the forms using the hierarchy. The Tree View initially displays only the widgets present on each of the form. For a detailed comparison for each of the widgets, click the icon in the Tree View and click the widget whose properties you want to view. If you want to view all the properties for all the widgets, click and Expand All. In the hierarchy if a widget is present on form1 and not on form2, the widget is denoted on form2 with a against it. If a widget is there on form1 and not on form2, the widget on form1 is denoted with a against it. All the conflicts or modified data in the forms are denoted by a against the conflicted widget, category, or property. If a widget(with the same ID) is present on two different parent containers on two different forms, it is denoted by a against it. You can execute any of the following actions using the Tree View: l l l l l l l Expand All: Expands all the widgets and the corresponding categories. This feature works only if you click the Show only conflicts and modified data icon first. Collapse All: Collapses all the widgets and the corresponding categories. This feature works only if you click the Expand All icon first. Copy all changes on selection to left: Enables you to copy any widget or property selected on the left form to the right form. Copy all changes on selection to right: Enables you to copy any widget or property selected on the right form to the left form. Show only conflicts and modified data: Displays all the conflicts and modified data on both forms. If you right-click against a widget or a property, you can Expand All or Collapse All the widgets and properties. You can also delete widgets and launch the Text Diff tool which provides a text comparison of the forms. Change the property of a widget on a form by clicking on the property in the Tree View. Note: It is recommended to port widgets from one form to another using the Graphical View. For example if on form1 a button is placed in an HBox, and you want to copy the button to form 2 which does not have an HBox, the button will take the entire remaining space on form2. Thus for better visual representation, use the Graphical View instead. 7.12.7 Graphical View The Graphical View presents a visual representation of widgets of the forms. The Graphical View enables you to compare widgets of the forms visually. To copy a widget from one form to another click the Toggle Copy Mode button present at the bottom of each form. Once the toggle mode is enabled a notification appears at the bottom right hand corner of the screen. To copy a form from left to right select the Toggle Copy Mode button on the left form and drag the widget across to the form on the right. To copy a form from right to left select the Toggle Copy Mode button on the right form and drag the widget across to the form on the left. You can also have the Toggle Copy Mode for forms on either side enabled at the same time. Using the Toggle Copy Mode you can also copy widgets within the same form as well. Any widget you click in the Graphical View automatically corresponds to the widget in the Tree View. Copyright © 2012 Kony, Inc. All rights reserved. Page 149 of 785 Working with Applications Kony Studio User Guide - 2.1 7.13 Adding Application Menu The Application Menu (App Menu) contains features that apply to the application as a whole, rather than to a specific application screen or window. Every application has several features within it for the users. You can choose to make some of these features available on every screen or specific screens of the application for easy navigation to these features. Note: On Android and iPhone platform, if you add more than five App Menu items, the menu items beyond the fifth App Menu item are grouped under the Menu item "more" (added automatically by the Android platform) and if you select "more", the rest of the Menu items are displayed in a list without any icons (even if the icons are set through code). For example, for a mobile banking application, the application features can include Accounts, Payments, Transfers, ATM Locations, and Services. These features can be placed under App Menu as illustrated in the figure below: Note: On BlackBerry and J2ME platforms, App Menu is also supported on a popup. To add application menu, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 150 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications view. 2. Right-click the required application and select App Menu. 3. The Application Menu Bar window appears as shown below. 4. Select a Skin (skin to be applied when the App Menu is rendered) and Focus Skin (skin to be applied when the App Menu is in focus). Note: The skins you have defined for the App Menu in the Skins View appear in this drop-down list. Note: BlackBerry does not support skin for App Menu. 5. Click to add a menu item in the App menu. 6. Enter a title for the menu item under Title. This is the title for the menu item in the App Menu. 7. Select an image for the icon under Icon in the Icon Location window. 8. Click Browse and select a default image and click OK. You can also select different images for different platforms on both Native App and Mobile Web. Copyright © 2012 Kony, Inc. All rights reserved. Page 151 of 785 Working with Applications Kony Studio User Guide - 2.1 Note: The image you select as the default image will be used on all platforms if you do not select platform specific images. 9. Select the platforms on which this menu item is to be rendered under Render. 10. Select the i18n Key for the menu item. 11. Define the action sequence that is to be executed on clicking this menu item. You will be directed to the Event Editor to define the action sequence. Note: For iPhone, you must specify an action sequence for every app menu item. 12. Go to Tablet Tab and define the app menu items for the tablet channel. Copyright © 2012 Kony, Inc. All rights reserved. Page 152 of 785 Working with Applications Kony Studio User Guide - 2.1 13. Go to Palm View tab. i. Select the Mode as grouped or non-grouped. grouped indicates that the menu items in the App Menu are grouped together and non-grouped indicates that the menu items are not grouped. For more information about the Mode property, see Kony Widget User Guide. ii. Select View as image or text. This property specifies if the App Menu is to be displayed as an image or as text on Palm. For more information, see Kony Widget User Guide. 14. Click Finish when you are done with adding the menu items. Note: The number of rows here under General/Tablet tab corresponds to the number of menu items in the App Menu for mobile/tablet channel. Important: While switching over App Menu items, avoid making service calls or execution of huge application logic. Switching between App Menu items should be instantaneous and smooth; executing huge application logic leads to a bad user experience. 7.13.1 Known Issue with App Menu on iPhone On iPhone, if there are more than five App Menu items, iPhone displays four App Menu items and a More button (native behavior). If you click the More button, the rest of the menu items are displayed. There is a known issue with supporting the native behavior of App Menu on iPhone platform. On iPhone platform when you create an App Menu that has more than four menu items, you need to follow a workaround. To overcome the known issue on iPhone, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 153 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Create the first three app menu items. 2. Create the fourth app menu item specifically with a label More and define an onclick event for this menu item. Define an action sequence that navigates to a new form. In this form, you can define the events for the rest of the menu items to navigate to other forms. 7.14 Working with Resources In the Kony Studio terminology, resources indicates images used within an application. All the images used within an application are listed under the resources folder of an application in the Applications View. The IDE provides you with an option to add new resources to the application. Note: The IDE currently supports only PNG, JPG, JPEG, and GIF formats for the images. l common - contains all the common resources, i.e, resources that are not platform specific. l mobilerichclient -Contains the following folder: l Common: contains all the resources common across Mobile native and Mobile Web channel. l Native: Contains resources to be used for native platforms like iPhone , blackberry, winmobile, android, palm, j2me, symbian. (This is just a container, images need to be placed in platform specific folders) l Web - Contains all the resources that are specific to mobile Mobile Web platforms like advandroid, advblackberry, adviphone, advpalm, bjs (locale specific folders, images240, images320, images480), normal (locale specific folders, images240, images320, images480), spaandroid , spablackberry , spaiphone. (This is just a container, images need to be placed in platform specific folders). l tablet - Contains the following folder: l l l l Common - contains all the resources for native and Web tablet platforms. Native - Native App platforms like iPad and Android tablet (androidtab ).(This is just a container, images need to be placed in platform specific folders). Web - contains all the resources that are specific to Mobile Web tablet channel (spanadroidtablet , spaipad , spaplaybook ). (This is just a container, images need to be placed in platform specific folders). desktop - Contains the following folders: l l l Common - contains all the resources for native and Web Desktop platforms. Native - contains all resources with respect to Native Desktop platforms like Windows 8. (This is just a container, images need to be placed in platform specific folders). Web - contains all the resources that are specific to Desktop Web. (This is just a container, images need to be placed in platform specific folders). Copyright © 2012 Kony, Inc. All rights reserved. Page 154 of 785 Kony Studio User Guide - 2.1 Working with Applications Examples During build for iPhone, 1. images from top common folder will be copied. 2. images from mobile\common folder will be copied, by overriding the step 1. images. 3. images from mobile\native\iphone will be copied, by overriding the 1 & 2 images. For existing apps, you have to manually split the images inside common folder to category specific common folders. Images are not allowed directly in following folders. 1.mobile,tablet,desktop 2.native,web 7.14.1 Naming Convention This section explains the naming convention you should follow while naming the images. The allowed characters in the image file names are: l lowercase alphabetical characters Note: The image name must start with a lowercase alphabetical character. l numerical characters l underscore (_) l period (.) Important: Do not use any reserved words or keywords (Java or Lua) as the file names for the images. The following table shows a few examples of valid and invalid file names for the images: Valid File Names Invalid File Names myicon.PNG Myicon.png accntsummary.JPEG aCCNT&summary.PNG account.details.jpg Details.jpg flightstatus123.png continue.PNG icon_2.gif Icon_2.gif Remarks The file name is invalid because it contains uppercase character. The file name is invalid because it contains uppercase characters and special character The file name is invalid because it contains uppercase character. The file name contains a Java keyword. The file name starts with an uppercase character. Note: Kony Studio does not recognize images that have invalid file names. Copyright © 2012 Kony, Inc. All rights reserved. Page 155 of 785 Working with Applications Kony Studio User Guide - 2.1 7.14.2 Adding Resources to an Application To add resources to an application, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Right-click resources and select New Resource.Add Image window appears. 4. In the General tab, execute the following: i. Click Browse and select a default image. ii. Click Mobile Native App tab, browse and select images for different platforms. Select these images if you want different images for these platforms. iii. Click Mobile Web tab, browse and select images for different platforms. Select these images if you want different images for these platforms. iv. Click Tablet Native App tab and select images for iPad, Android, and Playbook tablets. v. Click Tablet Web tab and select images for SPA iPad, SPA Android, and SPA Playbook. vi. Click Desktop/Kiosk tab and select images for desktop/kiosk. Note: To add multiple images per platform press Ctrl+<<image >> simultaneously and select OK. 5. After you define a locale, the i18n tab appears. Using the i18n tab execute the following: i. Select the required locale and the default image for that locale and Save that image as the Locale Default. ii. Click Mobile Native App tab and select images for different platforms (if required). iii. Click Mobile Web tab and select images for different platforms (if required). iv. Click Tablet Native App tab and select images for iPad, Android, and Playbook tablets. v. Click Tablet Web tab and select images for SPA iPad, SPA Android, and SPA Playbook. vi. Click Desktop/Kiosk tab and select images for desktop/kiosk. Note: To add multiple images per platform press Ctrl+<<image >> simultaneously and select OK. 6. Click OK. The newly added resource appears under resources folder. Note: The images are saved under the corresponding folders based on the platform for which they are applicable. Copyright © 2012 Kony, Inc. All rights reserved. Page 156 of 785 Working with Applications Kony Studio User Guide - 2.1 For example, if you add a generic image (independent of platform), it appears under the common folder. If you add an image for iPhone Native App, it appears under the iPhone folder within the mobilerichclient folder. Alternate Procedure 1. Go to <drive>:\<workspace>\<application_name>\resources folder. 2. Paste one or more images in PNG or JPEG format in the appropriate folder in the resources folder. 3. Launch Eclipse. 4. Open Kony Perspective. 5. Go to Applications view. 6. Select the application under which you have pasted the images and expand it. 7. Expand resources. 8. Right-click and select Refresh All. The newly added images appear under corresponding folder within the resources folder. 7.14.3 Adding Resources for Android 1. Go to Applications view. 2. Expand the application and navigate to resources > mobilerichclient> android. 3. Right - click android and select Add Resources folder. The Add Android Resource Folder appears. 4. You can create a folder in which resources are added based on the following l l l l l MCC and MNC: Creates a folder based on the Mobile Country Code and Mobile Network code. Add images or resources in the folder based on the MCC and MNC. You can add an image when you right click the newly created folder and select Add Resources. Screen Size: Screen size for which the application is built. Add the images based on the screen sizes specified. You can add an image when you right click the newly created folder and select Add Resources. Screen Aspect: Aspect for which the application is built. Add the images based on the screen aspect specified. You can add an image when you right click the newly created folder and select Add Resources. Screen orientation: Can be set as portrait or landscape. A folder is created accordingly under android. You can add an image when you right click the folder and select Add Resources. Ensure that the image name specified and added is the same as the image name specified in Splash Screen Properties. Dock mode: Creates a folder based on the dock mode specified. The dock mode can be car or normal. Add images in the respective folder based on the dock mode specified. You can add an image when you right click the newly created folder and select Add Resources. Copyright © 2012 Kony, Inc. All rights reserved. Page 157 of 785 Working with Applications l l l l l l l l Kony Studio User Guide - 2.1 Night mode: Mode in which the application is built. Add the images based on the mode specified. You can add an image when you right click the newly created folder and select Add Resources. Screen pixel density: Creates a folder based on the dpi of the device. Add the images based on the dpi specified.You can add an image when you right click the newly created folder and select Add Resources. Touchscreen type: Creates a folder based on the dpi of the device. Add the images based on the touch screen specified.You can add an image when you right click the newly created folder and select Add Resources. Keyboard availability: Creates a folder based on the keyboard availability set. Add the images based on the keyboard mode specified.You can add an image when you right click the newly created folder and select Add Resources. Primary text input method: Creates a folder based on the input method set . Add the images based on the method specified.You can add an image when you right click the newly created folder and select Add Resources. Navigation key availability: Creates a folder based on the navigation key availability. Add the images based on the availability specified.You can add an image when you right click the newly created folder and select Add Resources. Primary non-touch navigation method: Creates a folder based on the navigation set . Add the images based on the method specified.You can add an image when you right click the newly created folder and select Add Resources. Platform Version: Creates a folder based on the Android Platform version. Add the images based on the method specified.You can add an image when you right click the newly created folder and select Add Resources. 7.14.4 Retina Display on iPhone iPhone 4.0 has a high resolution screen (960x640) with a density of 326 ppi. When the screen density is more than 300 ppi, images, videos, text, and other objects appear very smooth with high clarity on the screen. This high resolution screen enables a very clear view of all the objects on the screen, which is similar to high quality printed output. Apple has named this technology Retina Display. All the iPhone applications are developed for 320x480 resolution. The images used in the application are automatically scaled up to suit the high resolution screen. When the images are scaled up for a high resolution screen, the clarity of images is distorted. The Retina Display feature ensures excellent image clarity by preventing automatic scaling. To support images within an application for Retina Display, follow these steps: 1. Create an image twice the pixel size of the original image. For more information, see the example given below. 2. Suffix the image name with @2x. Copyright © 2012 Kony, Inc. All rights reserved. Page 158 of 785 Working with Applications Kony Studio User Guide - 2.1 For example, if you have a company logo image logo.png , 50X50 pixels, which you want to use for a high resolution screen, create the same image with a pixel size of 100x100 and name it [email protected] . Note: Place the images created for the high resolution screen in the resources folder along with the other images. The application will automatically pick up the high resolution images for devices that support Retina Display. For more information about the Retina Display feature on iPhone, see http://www.apple.com/iphone/features/retina-display.html. 7.14.5 Retina Image on Mobile Web Kony Studio gives you an option to specify the Retina Image for the widgets in the skin forked for Mobile Web. To specify the Retina image, follow these steps: 1. Open the skin forked for iPhone Mobile Web. 2. Select the Style as Image. 3. Select the Location of the image. 4. Select Repeat image if you want the image to be repeated on the widget. 5. Select Enable retina image. 6. Browse and select the Retina image. 7. Select Repeat retina image if you want the retina image to be repeated on the widget. 8. Click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 159 of 785 Working with Applications Kony Studio User Guide - 2.1 Note: To provide retina images for any other purpose (for example, images in a Horizontal Image Strip) on Mobile Web, place the images (@2X) images in the resources\mobilethinclient\adviphone\ folder. 7.14.6 Support for Internationalization Images Kony Studio supports images for internationalization. For BlackBerry, you can use images specific to the internationalization locales. When you configure locales for internationalization, a folder specific to each locale is created under the resources/common folder and also under each platform specific folder as shown below: The resources folder has the following sub folders in it: l common - contains all the common resources, i.e, resources that are not platform specific This folder contains that are locale specific and specific to the screen size. Locale specific folders:Place images in the locale specific folders only for BlackBerry. For other platforms upload images in the common folder with unique names suffixed with the locale name say kony.png, kony_nl.png, kony_ch.png. o en_AU o en_US o fr_CA o it_IT Note: A folder is created for every locale you configure in the Internationalization window. Copyright © 2012 Kony, Inc. All rights reserved. Page 160 of 785 Working with Applications l l l Kony Studio User Guide - 2.1 desktop_kiosk - contains all the resources that are specific to Desktop channel. mobilerichclient - contains all the resources that are specific to mobile Native App platforms like iPhone, blackberry, winmobile, android, palm, j2me, symbian. mobilethinclient - contains all the resources that are specific to mobile Mobile Web platforms like advandroid, advblackberry, adviphone, advpalm, bjs (locale specific folders, images240, images320, images480), normal (locale specific folders, images240, images320, images480), spaandroid , spablackberry , spaiphone . l l tabletrichclient - contains all the resources that are specific to tablet Native App platforms like iPad and Android tablet (androidtab ). tabletrichclient - contains all the resources that are specific to Mobile Web tablet channel (spanadroidtablet , spaipad , spaplaybook ). To support images for internationalization, follow these steps: 1. Copy the images to be used for internationalization into the corresponding locale folder. Note: The images should have the same name. For example, if the general image is login.PNG , then the image internationalized for French Canada locale should also use the same name and be copied to resources/common/fr_CA folder. Important: When you copy images into the locale specific folder, those images are used for that locale on all platforms by default. 2. Copy the internationalized images to the locale specific folder under the corresponding platforms, if you want to use different images on different platforms. For example, if you want to use a different login.PNG on fr_CA locale for iPhone Native App, then copy the relevant image into the resources/common/mobilerichclient/iphone/fr_CA folder. 7.14.6.1 Using Internationalization Images Kony Studio picks up the right resources for internationalization in the following sequence: 1. locale specific directory 2. default directory. For example: l if you specify a.PNG as the image for en_US locale and if the device locale is en_US , then the image in resources/common/en_US is used. l if you specify a.PNG as the image and if the device locale is fr_FR , then the image in resources/common is used (if no image is defined for that locale). Copyright © 2012 Kony, Inc. All rights reserved. Page 161 of 785 Kony Studio User Guide - 2.1 Working with Applications 7.14.7 Resources on Android Resources specific to Android platform and specific to a locale/screensize/orientation/resolution should follow the below mentioned instructions. You should create the following folders in the resources/mobilerichclient/android/ folder: l l drawable-<language>-r<Region> when you have resources specific to locales only. For example, if you want to add a resource for en_US locale, then create a drawable-en-rUS folder and place the resource in drawable-en-rUS folder. drawable-<screensize> when you have resources specific to screen size only. Possible screen sizes are small, normal, large, and xlarge. For example, if you want to add a resource for normal screen size, then create a drawable-normal folder and place the resource in drawable- normal folder. l drawable-<orientation> when you have resources specific to orientation only. Possible values for orientation are land and port. For example, if you want to add a resource for landscape orientation, then create a drawable-land folder and place the resource in drawable- land folder. l drawable-<screen-pixel-density> when you have resources specific to resolution or screen-pixel-density only. Possible values for screen-pixel-density are ldpi, mdpi, hdpi, xhdpi, and nodpi. For example, if you want to add a resource for hdpi pixel density, then create a drawable- hdpi folder and place the resource in drawable-hdpi folder. If you have resources specific to a combination of these factors then you must follow precedence rules and name the folders appropriately. The precedence rules are as follows: 1. locales/language and region 2. screen size 3. orientation 4. screen pixel density. The following table explains a few examples: Folder Description drawable-en-rUS-land resources specific to US-English devices in landscape mode drawable-port-hdpi resources specific to devices in portrait mode with hdpi pixeldensity drawable-en-rUS-largeland drawable-en-rUS-largeland-hdpi resources specific to US-English large screen devices in landscape mode resources specific to US-English large screen devices in landscape mode with hdpi density Android 1.5 and lower versions do not support the following configuration qualifiers: Copyright © 2012 Kony, Inc. All rights reserved. Page 162 of 785 Kony Studio User Guide - 2.1 Working with Applications l Density/screen-pixel-density : ldpi, mdpi, hdpi, and nodpi l Screen size: small, normal, and large. This following table helps you in creating the resource folders as per screen size categories: Image folder name drawable-small drawable-normal (diagonal screen size) drawable-large Approximate Size Remarks 2" - 3.5" 3" - 4.5" This is the baseline size. 4.1" - 7" Introduced in Android 2.3 to anticipate tablets. drawable-xlarge 7" - 10.5" Important: To add this folder, ensure that you select the target SDK Version as Android 2.3 (API level 9) in the IDE Project Properties window. This following table helps you in creating the resource folders as per screen density (dpi) categories: Image folder name drawable-ldpi drawable-mdpi drawable-hdpi Approximate resolution ~120 dpi ~160 dpi ~240 dpi Remarks this is the baseline density on android platform Added in API Level 8 (Android 2.2). drawable-xhdpi ~320 dpi drawable-nodpi NA Important: To add this folder, ensure that you select the target SDK Version as Android 2.3 (API level 9) in the IDE Project Properties window. resources for images that should not be scaled on different density screens 7.14.7.1 How to Calculate DPI dpi = sqrt((width res * width res) + (height res * height res)) / (diagonal screen size in inches) For example, for a device with 480X854 resolution and screen size of 4.1 inch diagonal, the dpi = sqrt(480x480 + 854x854)/4.1 = 239 i.e., ~240 dpi. The folders created based on the screen density serve majority of the devices available in the market. But if you want to provide specific resource when running on, say a device with normal screen and high dpi, create a directory with combination of screen size and density like drawable-normal-hdpi and place the image here. Copyright © 2012 Kony, Inc. All rights reserved. Page 163 of 785 Working with Applications Kony Studio User Guide - 2.1 "Screen size" categories take a priority than the "Screen density". If you provide images within, say "drawable-large" and "drawable-hdpi" folders and if the device falls under both large and hdpi category, then Android system will give preference to screen size i.e., "drawable-large". Note: The drawable-## folders must be created under <project>/resources/mobilerichclient/android folder. 7.14.7.2 Add Resource Folders Kony IDE also provides option to create the above mentioned. 1. Right click resource/mobilerichclient/android folder under Applications View. 2. Select the appropriate ooption in the Add Android Resources Folder window. 3. Click OK. A new folder gets created under resources/mobilerichclient/android based on the options you select in the above step. For example, the folders like drawable, drawable-small, and so on are created. 7.14.8 9 Patch Background Kony Platform supports the 9-patch image feature developed by Android. The 9-Patch images help you to create edges for your images that can be used based on the orientation mode of the application. On Windows, a draw9patch.bat file exists in the Android SDK folder within the tools folder. On Mac, a draw9patch executable file exists in the Android SDK folder within the tools folder. Launch this tool to create 9-patch images. This tool is developed by Android. To launch the 9-patch tool, follow these steps: 1. Navigate to Android SDK folder. 2. Go to tools folder. 3. Run the file draw9patch.bat to launch the Draw 9-patch tool. Use this tool to create 9-patch images for your application. When you save the 9-patch image, you must save it with the name <imagename>.9.png . This naming convention must be followed for Kony Studio to pick up the corresponding images. For more information about using the 9-patch tool, see http://developer.android.com/guide/developing/tools/draw9patch.html. Important: The images used for creating 9-patch images must exist under \resources\mobilerichclient\android folder of your project. 7.15 Importing and Exporting Using the import and export option you can import or export the following : Copyright © 2012 Kony, Inc. All rights reserved. Page 164 of 785 Working with Applications l i18n keys l Services l Themes l Custom Libraries l Custom Fonts l Files Kony Studio User Guide - 2.1 7.16 Importing To import custom fonts, libraries, i18n keys, themes, and services: 1. Right click on the application and select Import > <<Object to be imported>> 2. Select the location where the source.zip is located. 3. Click Open. All the required resources are imported. Copyright © 2012 Kony, Inc. All rights reserved. Page 165 of 785 Working with Applications Kony Studio User Guide - 2.1 7.16.1 Importing Files 1. In the Application view, right click an application and select Import > Import Files. 2. Browse for the location where the files are located. 3. In the Into folder field, browse to the location where you want to save the file. 4. Click Finish. Alternate Procedures to import fonts To import custom fonts, follow these steps: 1. Go to Applications View. 2. Right-click the application for which you want to import custom fonts and select Integrate Third Party > Manage Custom Fonts. The Custom Fonts window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 166 of 785 Kony Studio User Guide - 2.1 Working with Applications 3. Click to display the Open window. Browse and select the font file that has the .ttf extension. Note: You can import only true type fonts (.ttf). 4. Select the platforms on which you want to install the font. The default selection is All. 5. Select the Scope of font. The scope indicates the place where you want to store the font. This can be either workspace or project. The font gets stored at the selected location. 6. If you want to delete a font, select the font and click . 7. Click OK. Alternately, you can also import custom fonts from the Skin window while adding or editing a skin. To import custom fonts, follow these steps: 1. Go to Skins View. 2. Select any widget, right-click and click Edit if a skin already exists. Else, click Add to add a new skin to the widget. For more information about creating skins, see Configuring Widget Skins. 3. Go to the Font tab in the Skin window. 4. Click Platform Specific Font Names. Note: You cannot select Platform Specific Font Names for forked skins. Copyright © 2012 Kony, Inc. All rights reserved. Page 167 of 785 Kony Studio User Guide - 2.1 Working with Applications 5. Click against the platform for which you want to add the font. The Custom Fonts window appears. 6. Click to display the Open window. Browse and select the font file that has the .ttf extension. 7. Select the platforms on which you want to install the font. The default selection is All. 8. Select the Scope of font. The scope indicates the place where you want to store the font. This can be either workspace or project. The font gets stored at the selected location. 9. If you want to delete a font, select the font and click . 10. Click OK. 7.16.2 Exporting i18n keys/Custom Libraries/Fonts To export i18n/Custom Libraries/Fonts of a project: 1. Right-click on the application and select Export > Internationalization/Custom Fonts/Custom Libraries. 2. Select the folder you want to export the defined i18n keys/ custom library/custom fonts to be copied to. 3. Click OK. Note: The font is installed on the selected platforms during build generation for Native App devices that have an OS support. While importing the fonts, you can specify the scope of the font as follows: workspace The font is available at the workspace level; this implies that all the applications within this specific workspace have access to the font. project The font is available only at the application level; this implies that the font is accessible only within the specific application. Important: l You can import custom fonts on all platforms except BlackBerry 10. l For BlackBerry, import custom fonts is supported only from 5.0 devices and above. l For iPhone, when you install the custom font, the custom font file name should match with the font's PostScript name displayed on the Font Info screen. (applicable only on Mac). Copyright © 2012 Kony, Inc. All rights reserved. Page 168 of 785 Working with Applications Kony Studio User Guide - 2.1 7.16.3 Exporting Themes To export a Theme of a project: 1. Right-click on the application and select Export>Themes. 2. Enter the name of the zip file where you want the themes to be copied to. 3. In the Export to field, enter the name of the folder where the zip file is to be saved. 4. Click Next. 5. Select the Skins to be exported. 6. Click Finish. 7.16.4 Exporting Services To export a Service of a project: 1. Right-click on the application and select Export > Service. 2. In the File Name field, enter the name of the zip file where you want the services to be copied to. 3. In the Export to field, enter the name of the folder where the zip file is to be saved. 4. Select the Service folders to be exported. 5. Click OK. All the exported resources are exported in a zip format. 7.17 Adding Templates in an Application When you want the same information to be displayed across all the datagrids, segments, or menus in the application, you have the provision to add a template for the following widgets to the application from Kony Studio. 7.17.1 Creating a Template for a DataGrid Widget Grid Templates are used to display the data as well as images in a DataGrid. The Grid Templates are used to: l Apply template type to columns in a DataGrid. l Apply template type to headers in a DataGrid. To create a grid template at the application-level, follow these steps: 1. Go to Applications View. 2. Expand the application for which you want to create the Grid Template. Copyright © 2012 Kony, Inc. All rights reserved. Page 169 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Navigate to templates > grids, right-click desktop and select New Grid Template. The Create a New Grid window appears. i. Enter a Name for the template. ii. Click Finish. A new form is created. iii. Drag and drop an HBox or a VBox within an HBox. Add any other widget within the Box. Note: Only HBox and VBox are supported on the form. You can put other widgets within these widgets. The widgets that can be dragged into the container are displayed in the Palette view. iv. A grid template is created. 7.17.2 Using a Grid Template To use Grid Template in an application, follow these steps: 1. Go to Applications view. 2. Expand the application in which you want to use the Grid Template. 3. Navigate to forms > desktop, right-click desktop and select New Form. The Create a New Form window appears. 4. Enter a name for the Form and click Finish. A new form is created. 5. Drag-drop a DataGrid on the web_<formname> and set data using Data property. You can set the created grid template for a row or a column using the Master Data Property of DataGrid. Previously in the Master Data property for a DataGrid you could only specify text for the column header template and column template. Using the Grid template, you can set images or buttons to be a part of the column header template or the column template. 7.17.3 Creating a template for a Segment Segment template enables you to define a template for section headers and rows of the segment. This is primarily useful for developers to achieve common look and feel of section headers along with few widgets added as part of section header of a segment. You can apply section/row header templates : l l l to have uniform look and feel of the section headers. to achieve the behavior of having widgets such as an Image and a label for all the section headers of the segment. to perform an action on the event of an onclick of an item or a widget in the section header. To create a segment template at the application-level, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 170 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Expand the application for which you want to create the Segment Template. 3. Navigate to templates > segments, right-click mobile/tablet/desktop and select New Segment Template. The Create a New Segment window appears. a. Enter a Name for the template. b. Click Finish. A new form is created. c. Drag and drop an HBox or a Scrollable Box onto the form. Note: Only HBox and Scrollable box are supported on the form. You can put other widgets within these widgets. d. Drag and drop the required widgets onto the HBox/Scrollable Box. Set the properties of these widgets. For more information, see Kony Widget User Guide. e. A segment template is created. 7.17.4 Using a Segment template To use Segment Template in an application, follow these steps: 1. Go to Applications view. 2. Expand the application for which you want to use section/row template. 3. For Rich Client applications, navigate to forms > mobile, right click mobile and select New Form. After you enter the required name, a form is created. 4. For Desktop Web applications: l l Navigate to forms > desktop, right-click desktop and select New Form. The Create a New Form window appears. Enter a name for the Form and click Finish. A new form is created. 5. Drag-drop a Segment on the <formname>. 6. To set the template to a segment, select the segment and go to Properties window and set the Section header and Row header template. For more information about setting a template, refer Widget User's Guide. 7.17.5 Creating a template for a Menu In Kony platform, a menu template is a container that can hold widgets in it. You can customize the behavior and look and feel of the menu template. The customized behavior is applied across the forms where-ever the Menu container is used. You can apply menu templates to: Copyright © 2012 Kony, Inc. All rights reserved. Page 171 of 785 Working with Applications Kony Studio User Guide - 2.1 l have uniform look and feel of the parent Menus. l have uniform look and feel when an item is focused in a Menu Container. l perform an action on the event of an onclick of an item in the Menu Container. l define uniform margins and paddings for the Menu/MenuItems. To create a menu template at the application-level, follow these steps: 1. Go to Applications View. 2. Expand the application for which you want to create the Menu or MenuItem Template. 3. Navigate to templates > menus, right-click desktop and select New Menu Template. The Create a New Menu window appears. a. Enter a Name for the template. b. Click Finish. A new form is created. c. Drag and drop an HBox or a VBox within an HBox. Note: Note: Only HBox and VBox are supported on the form. You can put other widgets within these widgets. d. Drag and drop the required widgets onto the HBox/VBox. Set the properties of these widgets. e. A menu template is created. 7.17.6 Using Menu Templates To use Menus Template in an application, follow these steps: 1. Go to Applications view.Expand the application for which you want to use Menus. 2. Navigate to forms > desktop, right-click desktop and select New Form. The Create a New Form window appears. 3. Enter a name for the Form and click Finish. A new form is created. 4. Drag-drop a Menubar on the web_<formname>. 5. Add subsequent Menus and menuitems. 6. To set the template to a menu/menuitem, use the masterData property of the widget. For more information on setting the templates refer the Widget User's Guide. 7.17.7 Creating a Template for a Map callout Map Templates are used to set a template for a map callout. For more information about map callouts refer Widget User Guide. Copyright © 2012 Kony, Inc. All rights reserved. Page 172 of 785 Working with Applications Kony Studio User Guide - 2.1 To create a map template at the application-level, follow these steps: 1. Go to Applications View. 2. Expand the application for which you want to create the Grid Template. 3. Navigate to templates > Map, right-click mobile/tablet/desktop and select New Map Template. The Create a New Map window appears. a. Enter a Name for the template. b. Click Finish. A new form is created. c. Drag and drop an HBox or a Scrollable Box onto the form. Note: Only HBox and Scrollable box are supported on the form. You can put other widgets within these widgets. d. Drag and drop the required widgets onto the HBox/Scrollable Box. Set the properties of these widgets. For more information, see Kony Widget User Guide. e. A map template is created. 7.17.8 Using template for a Map callout To use Map Callout Template in an application, follow these steps: 1. Go to Applications view. 2. Expand the application for which you want to use callout template. 3. For Rich Client applications, navigate to forms > mobile, right click mobile and select New Form. After you enter the required name, a form is created. 4. For Desktop Web applications: l l Navigate to forms > desktop, right-click desktop and select New Form. The Create a New Form window appears. Enter a name for the Form and click Finish. A new form is created. 5. Drag-drop a Map on the <formname>. 6. To set the template to a Map callout, select the map and go to Properties window and set the callout template. For more information about setting a template, refer Widget User's Guide. 7.17.9 Creating a Template for a Tab Widget Tab Templates are used to display the data as well as images in a Tab header. To create a tab template at the application-level, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 173 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Expand the application for which you want to create the Tab Template. 3. Navigate to templates > Tab, right-click desktop and select New Tab Template. The Create a New Tab window appears. i. Enter a Name for the template. ii. Click Finish. A new form is created. iii. Drag and drop an HBox or a VBox within an HBox. Add any other widget within the Box. Note: Only HBox and VBox are supported on the form. You can put other widgets within these widgets. The widgets that can be dragged into the container are displayed in the Palette view. iv. A tab template is created. 4. Right-click the template and fork it for Desktop_web. 7.17.10 Using a Tab Template To use Tab Template in an application, follow these steps: 1. Go to Applications view. 2. Expand the application in which you want to use the Tab Template. 3. Navigate to forms > tab, right-click desktop and select New Form. The Create a New Form window appears. 4. Enter a name for the Form and click Finish. A new form is created. 5. Drag-drop a DataGrid on the web_<formname> and set data using Data property. You can set the created tab header template for a tab header in the Properties pane of the Tab. For more information about the Tab template refer the Widget User Guide. 7.17.11 Adding Headers and Footers When you want the same information to be displayed across all the forms in the application, you have the provision to add headers or footers to the application from Kony Studio. You can put such information in the header or footer, depending on the requirement. To create a header/footer at the application-level, follow these steps: 1. Go to Applications View. 2. Expand the application for which you want to create the header/footer. 3. Expand headers, right-click mobile and select New Header Template to create a header. The New Header window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 174 of 785 Working with Applications Kony Studio User Guide - 2.1 i. Enter a Name for the header. ii. Click Finish. A new form is created. iii. Drag and drop a HBox or a Scrollable Box onto the form. Note: Only HBox and Scrollable box are supported on the form. You can put other widgets within these widgets. iv. Drag and drop the required widgets onto the HBox/Scrollable Box. Set the properties of these widgets. For more information, see Kony Widget User Guide. v. A header is created. 4. Expand footers, right-click mobile and select New Footer Template to create a footer. The New Footer window appears. i. Create a footer following the same steps that you used to create a header. Note: To create headers or footers for a tablet and desktop channel, follow similar steps as stated above. Headers and Footers are referred as following in the Mapping Editor: • app.headers.<TopLevelHBox>.<Widget>.property - for headers • app.footers.<TopLevelHBox>.<Widget>.property - for footers 7.17.12 Context Menu- Templates Note: Context Menu templates are supported only on Desktop Web platform. 7.17.12.1 What is a Template for a Context Menu In Desktop Web, when you right-click a Menu Container or a Box the context specific menu will be displayed with the array of menu items. A Context Menu Template is essentially a template having a Menu Container in which the developer customizes the overall look and feel of the context menu. 7.17.12.2 Where to use a Context MenuTemplate Context Menu Templates are used to display how the data is presented to the end user when a context menu pops up. 7.17.12.3 Creating a Template for Context Menu When you want the same template to be displayed across all the Context Menus in the application, you have a provision to add a Context Menu Template using Kony Studio. To create a context menu template at the application-level, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 175 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Expand the application for which you want to create the Context Menu Template. 3. Navigate to templates > contextmenus, right-click desktop and select New ContextMenu Template. The Create a New Menu dialog appears. i. Enter a Name for the template. ii. Click Finish. A new form is created. iii. Drag and drop a Menu container in the form. iv. Set the required properties and click Save. A Context Menu template is created. 7.17.12.4 Using Context Menu Template You can create separate templates for each context menu using the above process. In Desktop Web, when you Right-click a Menu Container or a Box the context specific menu will be displayed with the array of menu items. To use Context Menu Template in an application, follow these steps: 1. Go to Applications view. 2. Expand the application for which you want to use Context Menu. 3. Navigate to forms > desktop, right-click desktop and select New Form. The Create a New Form window appears. 4. Enter a name for the Form and click Finish. A new form is created. 5. Right-click on the newly created form and select Fork. The Platform Selection window appears. 6. Select Desktop_web and click OK. The form is now forked for Desktop_web and new window appears as web_<formname>. Note: The development activities for desktop web should happen in web_<formname> only. Although the newly created form, remains accessible in the desktop forms. 7. Drag-drop a Box or a Menu container on the form and set data using the contextMenu property under Desktop Web. 7.18 Configuring Headers and Footers After you have created headers and footers, you need to configure them so that they are used within the application. To configure headers/footers, follow these steps: 1. Go Applications View. 2. Expand the application for which you want to configure header/footer. Copyright © 2012 Kony, Inc. All rights reserved. Page 176 of 785 Kony Studio User Guide - 2.1 Working with Applications 3. Expand forms and open the form for which you want to configure the header/footer. 4. Go to Properties View. i. Scroll down to the Header and Footer properties. ii. Select the appropriate header/footer against the corresponding property. Note: All the headers/footers you have created appear in the list against the corresponding properties. 5. The selected header and footer will be applied to the form. The following is a snapshot of a form with header and footer applied to it: 7.19 Working with Skins A widget skin defines the look and feel of the widget when it is rendered on the form in an application. You can specify different skins for different widgets, or different skins for different platforms. The IDE allows you to create skins and specify skins for widgets while setting the properties. For more information about setting widget properties, see Kony Widget User Guide. To specify different skins for different platforms, you need to fork skins. For more information about forking skins, see Forking Skins. The skins are stored in skin.xml file. The platform specific skins are stored in separate xml files: Platform iPad iPhone Android File Name ipadskin.xml iphoneskin.xml androidskin.xml Copyright © 2012 Kony, Inc. All rights reserved. Page 177 of 785 Kony Studio User Guide - 2.1 Working with Applications Platform BlackBerry J2ME Palm Symbian Windows Mobile File Name bbskin.xml j2meskin.xml palmskin.xml symbianskin.xml winmobskin.xml l xhtmladvandroidskin.xml l xhtmladviphoneskin.xml l xhtmladvotherskin.xml Advanced l xhtmladvpalmskin.xml xhtmlbjsskin.xml l xhtmllargeskin.xml l xhtmlmediumskin.xml l xhtmlsmallskin.xml l Mobile Web Basic Note: When you add a widget to a form, the widget uses the default Kony skin unless you specify a skin for the widget under Properties. You can create skins for the widgets. 7.19.1 Kony Default Skins Skin Defaults let you specify common skins for widgets in different states (normal and focus). These skins are also known as Kony Default Skins. Using the Kony Default Skins you can provide a uniform look and feel for the widgets across various platforms. For example, if you specify btnSkinNormal as the Normal skin for Button under Application Themes, all the buttons in the application will use btnSkinNormal as the Normal Skin for buttons. Though the Application Themes define a common skin for a particular widget across the application, you can still specify a different skin for a widget by selecting a different skin under the widget properties. However, this should be done only if required. To specify application themes, follow these steps: 1. Go to Applications View. 2. Select the required application. Copyright © 2012 Kony, Inc. All rights reserved. Page 178 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Right-click and select Skin Defaults. The Application Skin Defaults window appears. 4. Select the widget for which you want to select themes. 5. Select Normal and select a skin from the drop-down list. 6. A list of all the skins defined for this widget appears in the drop-down list. 7. Add Skin if you want to create a new skin. You can perform the following actions on a skin from this window itself rather than navigating to the Skins window: i. add ii. edit Copyright © 2012 Kony, Inc. All rights reserved. Page 179 of 785 Kony Studio User Guide - 2.1 Working with Applications iii. fork iv. delete. 8. Similarly, define a theme for the Focus skin following the same steps. 9. Click Finish. 7.19.2 Themes Kony Studio provides a default theme that has a set of skins defined for all the widgets within an application. The skins in this theme can be applied to widgets to get a different look and feel for the widgets. The Themes View is embedded in the Skins View. A drop-down list indicating the current theme appears in the Skins View. you can see theme to which all the skins are associated with. Kony Studio also provides you to create themes and associate skins with them. When you create a theme, it is created using the default theme as the base. All the skins available in the skins available in the default theme are copied to the created theme. The IDE allows you to add, modify, rename, copy, fork, clone, and delete skins within a theme. Important: Any changes you make to the skins within a theme are limited only to that theme. Kony Platform provides a set of APIs that allow you to perform different actions with themes. The theme you create using the IDE can only be applied using the theme.setcurrenttheme API. For more information about the APIs related to Theme, see Kony API Reference Guide. 7.19.2.1 Create a Theme To create a theme, follow these steps: 1. Navigate to Skins View. 2. Click Add New Theme icon ( ). 3. Enter a name for theme in the New Theme window and click OK. A new theme with the specified name is created. All the skins in the default theme are copied to the new theme. 4. Select the new theme in the drop-down list to see a list of the skins in the new theme. 7.19.2.2 Delete a Theme Kony Studio provides you with an option to delete a theme when it is no longer used in the application. When you delete a theme, you must be aware that all the skins associated with that theme are also deleted. Click the Remove theme ( ) icon to delete a theme. Copyright © 2012 Kony, Inc. All rights reserved. Page 180 of 785 Working with Applications Kony Studio User Guide - 2.1 Important: You can only delete themes that you have created manually. You cannot delete the default theme available in the IDE. 7.19.3 Native Skins Kony Studio also provides you the ability to use the native skins (skins that give the native look to the widgets) on certain platforms. Note: The IDE supports native skins only on iPhone and Android platforms. The native skins are applicable to the following widgets: l Button l TextBox. To use the native skins, follow these steps: 1. Go to Skins View. 2. Expand the required widget (Button or TextBox). 3. Select the iPhone or Android skin. If there is no skin available on these platforms, fork the skins for these platforms. 4. Right-click the required skin and select Edit. 5. Select the Use Native option to the right of the Edit Skin window. 6. Click the Font tab. You have the option to override the native attributes of Font. 7. Select Override against the attribute that you want to override. When you override a specific attribute, the overridden attribute is used in the skin instead of the native attribute. Copyright © 2012 Kony, Inc. All rights reserved. Page 181 of 785 Working with Applications Kony Studio User Guide - 2.1 Change/modify the required attributes. Note: You can override only the Font attributes for a native skin. 8. Click Finish. The native skin is used for the selected widget on the selected platform (with the overridden attributes, if any). 7.19.4 Add Skins If you want to apply other skins to the widgets apart from the skins available by default in the IDE, you can use the option to add a skin. To create widget skins, follow these steps: 1. Go to Skins view. 2. Right-click the widget for which you want to create a skin and select Add. The Add New Skin window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 182 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Enter a name for the skin in the Name field. The widget for which you are editing or creating the skin appears in the Widget Type field. Note: The default skin is used as the starting point. 4. Click the Background tab. i. Select the style. This style can be Transparent, One Color, Two Colors, or Image. For a list of applicable background styles on various widgets, see Skin Attributes. l Transparent If you select Transparent as the style, the skin background will be transparent. Copyright © 2012 Kony, Inc. All rights reserved. Page 183 of 785 Working with Applications Kony Studio User Guide - 2.1 For example, a button with background style as Transparent appears as shown below on BlackBerry Native App: l One Color If you select One Color as the style, you can select the color and also the transparency level for the background. For example, a button with background style as One Color appears as shown below on BlackBerry Native App: Copyright © 2012 Kony, Inc. All rights reserved. Page 184 of 785 Working with Applications l Kony Studio User Guide - 2.1 Two ColorsIf you select Two Colors as the style, you can select top and bottom colors, and also the transparency percentage for each color. You can specify the pattern as: o Vertical Gradient. If selected, a gradient is applied from the top color to the bottom color. o Vertical split. If selected, the top color and bottom colors appear as two different colors one after the other (as a split). Note: Vertical Split is not supported on IE8 browser. For example, a button with background style as Two Colors appears as shown below on BlackBerry Native App: l Image If you select Image as the style, you can specify an image as the background. You can in turn specify different images for Native App, Mobile Web, and Tablet Channels. Note: If you specify Image as the background for form, on BlackBerry and J2ME platforms ensure that the image covers the entire screen width and height (for a good user experience while scrolling on the form) to avoid jagged lines affect. Note: If you specify Image as the background for a button, on Thin Client and SPA platforms you have an option to set image size as 100% in cases where the image goes beyond the entire screen. For example, a button with background style as Image appears as shown below on BlackBerry Native App: Copyright © 2012 Kony, Inc. All rights reserved. Page 185 of 785 Working with Applications Kony Studio User Guide - 2.1 For a switch, you can specify the Style as Image only. In the Left Image field, specify the image to be displayed to the left of the switch. In the Right Image field, specify the image to be displayed to the right of the switch. The skin forked for BlackBerry (for any widget that can have an image as a background) supports Three Image background. When you select the Style as Image, you have the option to select the Type, Pattern, and the image(s). Type - Single Image or Three Image. For Single Image, select the location of the image. For Three Image, select the left, middle, and right images. Three Image type is used to give a three image-patch look to the widget to which this skin is applied. Middle Image is mandatory while left and right images are optional. Pattern - normal or tiled (applicable only for Single Image). The following are various possible scenarios for three image background: n If three images have the same width, the three images occupy equal width on the widget. n If the sum of width of three images is greater than the widget size (height), then no images are visible (first middle image is ignored, if still the left and right images do not fit the space then all the images are ignored). n If the height of the middle image is greater than the widget size (height), the widget occupies the height of the image. n If the width of the middle image is greater than half of the widget size (width), the middle image stretches and occupies the entire width. The following images illustrate the three-patch background on BlackBerry platform: Copyright © 2012 Kony, Inc. All rights reserved. Page 186 of 785 Working with Applications Kony Studio User Guide - 2.1 5. Click the Font tab. i. Select the font Color. ii. Enter Transparency percentage. The percentage ranges from 0 to 100, 0 indicates minimum transparency and 100 indicates maximum transparency. iii. Enter font Size in terms of percentage. Note: The percentage you specify here is calculated based on the Base Font you enter in Mobile Web Properties. Base fonts are applicable only on Mobile Web/SPA/Desktop Web platforms. iv. Select the font weight. The weight can be normal or bold. Note: This property is not supported on iPhone. v. Select font style. This can be none, italic, or underline. Note: This property is not supported on iPhone. vi. Click Platform Specific Font Names. Font Names window appears as shown below. You can select fonts for individual platforms on Native App and Mobile Web separately. Note: You can only see a list of fonts that are installed on the computer. You can also import custom fonts. For more information about importing custom fonts, see Importing Custom Fonts. Importing Custom Fonts is supported only for Native App channels. Copyright © 2012 Kony, Inc. All rights reserved. Page 187 of 785 Kony Studio User Guide - 2.1 Working with Applications 6. Click the Border tab. i. Enter the width of the border in pixels. ii. Select a Color for the border. iii. Enter Transparency percentage. The percentage ranges from 0 to 100, 0 indicates minimum transparency and 100 indicates maximum transparency. Note: The Color Palette and Transparency fields are enabled only if the border width is a nonzero value. iv. Select the border style. This style can be plain or rounded. Note: Rounded border is not supported on basic and BJS versions of Mobile Web. The browsers do not provide such ability. Note: Transparency for widgets is not supported for background, font, and borders on J2ME. This is a platform limitation. 7. Click the Mobile Web (CSS) tab. i. Select Use Custom CSS option. Selecting this option enables the text box where you can enter your own code for the CSS. This CSS will be applied to the widget on Mobile Web. 8. For a chart, click the Chart_2D_3D Properties tab. i. Select the colors for X Axis color, Y Axis color, Chart Area Color, Chart Wall color, Chart Grid Color, and Chart Font color. l l l l X Axis color - Specifies the x axis color. This is applicable for Area, Line, and Column Charts only. Y Axis color - Specifies the y axis color. This is applicable for Area, Line, and Column Charts only. Chart Area color - Specifies the color of the area inside the border line where the chart is drawn. Chart Wall color - Specifies the color for the area inside chart area where the chart is drawn. l Chart Grid color - Specifies the color of the grid lines. l Chart Font color - Specifies the color of the font used for the chart. ii. Click Finish. 9. Click the Platforms tab. Select the platforms on which you want the skin to be applicable. Note: By default, the skin is applicable on all platforms. You have to explicitly deselect the platforms on which you want the skin to be inapplicable. 10. Click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 188 of 785 Kony Studio User Guide - 2.1 Working with Applications 7.19.5 Add Skin for a Grid Calendar When you add a skin for the Calendar widget, there are two additional skins: l grid calendar skin l cell skin. Grid calendar is a type of view for the calendar supported by the following platforms: l iPhone l Android l BlackBerry. The following table illustrates the various properties available when you select the type of calendar as grid calendar: Property iPhone/iPad Skin Cell Skin Selected Cell Skin Focus Cell Skin Applicable Applicable Applicable NA Today Skin Applicable Android Applicable Applicable Applicable Applicable NA Today Cell Skin is applied NA Today Cell Skin BlackBerry Applicable Applicable Applicable Applicable Applicable NA Applicable Today Skin is applied Today Skin is applied NA Weekend Skin Applicable Non Active Days Skin Applicable Holiday/Disable Cell Skin Mode On Screen Left Navigation Image Right Navigation Image Holiday/Disable Cell Skin is applied NA Holiday/Disable Cell Skin is applied Applicable Applicable NA Applicable NA Applicable Applicable NA NA NA NA Applicable NA Can be specified in the Grid Calendar skin NA Can be specified in the Grid Calendar skin Applicable Applicable Can be specified in the Grid Calendar skin NA Can be specified in the Grid Calendar skin Copyright © 2012 Kony, Inc. All rights reserved. Page 189 of 785 Working with Applications Kony Studio User Guide - 2.1 For more information about what each of the above stated properties mean, see Kony Widget User Guide. When you add a skin for the grid calendar, apart from all the tabs mentioned in the previous section, General tab also appears in the Skin window. Important: The attributes you specify in the Grid Calendar skin under General, Background, Border, and Font tabs are applied only for iPhone and BlackBerry platforms due to a platform limitation on Android. To specify the attributes for Android platform, you must fork the skin for Android. l The General tab lets you specify the following attributes: o Grid Line Color - specifies the color of the grid line in the grid calendar Note: The Grid Line Color specified here does not apply on Android. To specify a Grid Line Color for Android, you must fork the skin for Android. l o Left Navigation Image - image that is used to navigate to the left in the grid calendar o Right Navigation Image - image that is used to navigate to the right in the grid calendar. In the Font tab, you have the following additional options apart from the options explained in the previous section: o Font attributes for Month Text o Font attributes for Days Text. To set the skin attributes for the skin forked for Android, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 190 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Skins View. 2. Expand Calendar -> Grid Calendar. 3. Expand the grid calendar skin and select the skin that you have forked for Android. 4. Open the skin forked for Android in any of the following ways: l Double-click. l Right-click and select Edit. 5. Specify the attributes under different tabs: l Background tab o If you select the style as Transparent, it indicates that the grid line is transparent. o If you select the style as One Color, it indicates that the grid line will have the specified color. l Border tab l Font tab o Specify the font Color, Transparency, Size, Weight, and Style. These attributes are applied to Months Text. 7.19.6 Edit Skins You can edit the skins that are available by default in the IDE or the skins that you have created. To edit a skin, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 191 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Navigate to Skins View. 2. Expand the widget for which you want to edit the skin. 3. Select the skin that you want to edit, right-click and select Edit. A. In the Edit Skin window that appears, select theme in which you want to edit the skin. The themes are visible only when you have custom defined themes in the application. B. Modify the required skin attributes and click Finish. 7.19.7 Instant Preview Kony Studio has the capability to instantly show the preview of the skin applied to any widget. That is, the IDE has the WYSWYG (What You See is What You Get) capability. Margins, Padding, or Skins applied to various widgets on the Form Designer are instantly visible in the IDE. You can view how the widget appears when a particular skin is applied to it. This feature is useful when you make changes to the attributes of the skin. You do not need to build the application and view the application on the emulator to understand the behavior of a specific skin. Note: The Instant Preview is enabled only if you have enabled Enable skin preview option in the Kony Studio Preferences window. For example, when a skin that has the following attributes is applied to a form, the form appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 192 of 785 Kony Studio User Guide - 2.1 Working with Applications Note: The appearance of widgets in the IDE is just indicative of the original appearance. The IDE does not replicate the look and feel of the widgets on the actual mobile device. Note: Instant Preview is not applicable for Segmented UI, Browser, and Rich Text widgets. 7.19.8 Configure Skins You can apply a suitable or appropriate skin to the widgets in different states (normal, focus, and so on depending on the widget) as per your requirement. To apply skin to a widget, follow these steps: 1. Select a widget in the Outline view. 2. Go to Properties view. 3. Scroll to Skin. 4. Select Normal and click . A window opens with a list of all the skins defined for that widget. Note: If you do not select any skin (None), theme is applied to the widget. If you do not select any theme (None), the default skin is applied to the widget. 5. Select a skin from the list. For more information, see Kony Widget User Guide. 6. Click OK. The selected skin will be applied to the widget. Note: When you delete a skin that is applied to any widget, the default skin is applied to that widget. 7.19.9 Fork Skins When you want the same widget to appear with a different look and feel on different platforms, you fork the skins. After you have forked the skin for a specific platform, you can specify that skin for the widget in the widget properties. When you make the widget available on that platform, the widget appears with the forked skin. For more information about setting widget properties, see Kony Widget User Guide. To fork widget skins, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 193 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Skins view. 2. Select the widget for which you want to fork the skin. 3. Expand the widget to view the available skins. 4. Right-click the skin you want to fork and select Fork. 5. Fork window appears as shown below. Select the platforms for which you want to fork the selected skin. Note: In this window, you can select only the platforms on which the skin was not forked. Copyright © 2012 Kony, Inc. All rights reserved. Page 194 of 785 Working with Applications Kony Studio User Guide - 2.1 6. Click Finish. The forked skin appears as shown below in the Skins view. 7. Right-click the forked skin and select Edit to edit it and set the attributes for the skin. Forked skins are categorized as Mobile Native App and Mobile Web based on the platforms on which the skin is forked. The Edit Skin window appears as shown below (when you fork the skin for Native App). Copyright © 2012 Kony, Inc. All rights reserved. Page 195 of 785 Working with Applications Kony Studio User Guide - 2.1 The Edit Skin window appears as shown below (when you fork the skin for Mobile Web). For a skin forked on Mobile Web, you can set the top, left, border, right borders as shown in the above screen. You can specify the width, color, transparency, and style of the border for each of the right, left, bottom, and right borders. Note: You need to edit each forked skin individually to set the skin properties. For example, if you have forked the skin for iPhone and BlackBerry platforms, you need to edit skins for both iPhone and BlackBerry individually. Copyright © 2012 Kony, Inc. All rights reserved. Page 196 of 785 Working with Applications Kony Studio User Guide - 2.1 Note: When you fork the Switch skin for Mobile Web, you have the option to specify Left and Right Skins. You can also specify the Progress Indicator image for Mobile Web channel when you fork a skin for Mobile Web. The Progress Indicator tab of the forked skin allows you to specify a Progress Indicator image and its position. 8. Set the properties according to the requirement and click Finish. For more information about setting properties, see Kony Widget User Guide. 7.19.10 Delete Skins Kony Studio provides you the ability to delete the skins that are part of the default skin. Note: You cannot delete a skin that is associated with a custom defined theme. To delete a skin, follow these steps: 1. Go to Skins View. 2. Select the Theme as default from the drop-down list. 3. Expand the widget for which you want to delete a skin. 4. Select a skin, right-click, and select Delete. 5. Select Yes in the confirmation window that appears. The selected skin is deleted. Important: If you delete a skin that is applied to a specific widget, no skin is applied to the widget. 7.19.11 Rename Skins Kony Studio provides you the option to rename skins. Renaming skins is useful when conflicts arise between the naming conventions of forms, widgets, and skins. To rename a skin, follow these steps: 1. Go to Skins View. 2. Expand the widget for which you want to rename a skin. 3. Select a skin, right-click, and select Rename. Copyright © 2012 Kony, Inc. All rights reserved. Page 197 of 785 Working with Applications Kony Studio User Guide - 2.1 4. Enter a new name for the skin in the Rename window that appears. The name must be unique. 5. Click OK. The skins view is refreshed and the skin with the new name appears under the list of skins. 7.19.12 Search Skins The Skins View toolbar provides you with an option to search for the skins in the available list. If there is a huge list of skins, it is cumbersome to navigate to the required skin. In such a case, search is a useful option as using this feature, you can filter the list to display on only skins that match the search criteria. To search for skins, follow these steps: 1. Go to Skins View. 2. Click icon on the Skins View toolbar. The Skins window appears. The default view of the Skins window is to list all the available skins. If you want to view the skins widget-wise, select Show Categories. The view of the window is as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 198 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Enter a few characters in the Search field to search the skins that you want. This functionality supports the search with * character. The following are different possible combinations for searching: l <searchstring> - lists all the skins that match with the <searchstring> l *<searchstring> - lists all the skins that contain the <searchstring> l <searchstring>* - lists all the skins that begin with the searchstring and may or may not have other Copyright © 2012 Kony, Inc. All rights reserved. Page 199 of 785 Working with Applications l Kony Studio User Guide - 2.1 * - lists all the skins; this is similar to the default view 7.19.13 Clone Skins Cloning Skins is a useful option when you want to replicate the forked skins for other platforms. For example, there is a skin btnSkin for a Button and you forked it for Android. The forked skin for Android has a set of defined properties. If you want the same properties to be replicated on other platforms, you can clone this Android skin rather than forking the skin from the parent level. Clone All option lets you clone all the skins available on one platform to other platform(s). All the skins defined on one specific platform (irrespective of the widgets) can be cloned to other platform(s). To clone widget skins, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 200 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Skin View. 2. Select the widget for which you have the forked skins available. Note: Forked skins appear under the head Mobile Native App Channel or Mobile Web Channel based on the platform for which the skin was forked. 3. Expand the appropriate platform channel. 4. Right-click the required skin and select Clone. The Platform Selection window appears as shown below: Note: When you clone the skin, all the properties that were set for the forked skin will be applied to the cloned skin. Copyright © 2012 Kony, Inc. All rights reserved. Page 201 of 785 Working with Applications Kony Studio User Guide - 2.1 5. Select the platforms on to which you want to clone the skin and click OK. The cloned skins appear along with the forked skins categorized accordingly in the Skin View. Note: The IDE does not clone a skin if there is no difference between the parent skin and the forked skin that you want to clone. For example, if you have a skin btnSkin for a Button and you fork it for Blackberry without changing any properties, then you cannot clone the Blackberry skin to other platforms. To clone all skins, follow these steps: 1. Go to Skin View. 2. Select below: at the top-right corner of the Skin View. The Platform Selection window appears as shown 3. Select the platform from which you want to clone all skins in the Platform drop-down list. 4. Select the platform(s) to which you want to clone all the skins. Copyright © 2012 Kony, Inc. All rights reserved. Page 202 of 785 Working with Applications Kony Studio User Guide - 2.1 5. Click OK. The skins are cloned for the target platforms and available for use in the Skin View (categorized appropriately). 7.19.14 Import/Export Skins The IDE provides you with the option of importing and exporting skins used in an application. The advantage of importing or exporting skins is to re-use them across applications based on the requirement. 7.19.14.1 Import Skins If you want to use the skins that are part of a different application, you can import those into the application and start using them. To import skins, follow these steps: 1. Go to Skins View. 2. Click icon on the Skins View toolbar. The Import window appears as shown below: 3. Browse and locate the skin.zip file that you want to import into the application. Note: The IDE does not accept any file except for a ZIP file. 4. Kony Studio unzips the skin.zip file to the skin folder at the same location. Copyright © 2012 Kony, Inc. All rights reserved. Page 203 of 785 Working with Applications Kony Studio User Guide - 2.1 5. Select Skins for Import window appears as shown below: 6. Select the skins that you want to import into the application. Note: If the application already has skins with the same name, the skins existing in the application will be overwritten if you do not specify a new name. 7. Select Overwrite images if they exist if you want to overwrite the images in the skins (already existing in the application). 8. Click OK. The selected skins are imported into the application are ready for use. 7.19.14.2 Export Skins If you want to make use of the skins used in one application in another application, you should export the skins so that they can be used in that application. To export skins, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 204 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Skins View. 2. Click icon on the Skins View toolbar. The Export window appears as shown below: 3. Browse and select the destination folder to which you want to export the skins in the application. Select Skins for Export window appears. i. Select the skins that you want to export. ii. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 205 of 785 Kony Studio User Guide - 2.1 Working with Applications 4. The skins are exported to the selected folder in a ZIP file, skin.zip . The skin.zip file contains the following files: skin.zip file iphoneskin.xml androidskin.xml bbskin.xml winmobskin.xml palmskin.xml symbianskin.xml j2meskin.xml ipadskin.xml tabrcandroidskin.xml xhtmladviphoneskin.xml xhtmladvandroidskin.xml xhtmladvbbskin.xml xhtmladvpalmskin.xml xhtmlbjsskin.xml xhtmllargeskin.xml skin.xml 7.19.15 Copy Skins Kony Studio provides you the option to copy skins. Copying skins is useful when you want to use the same attributes for a skin as that of an existing skin. To copy a skin, follow these steps: 1. Go to Skins View. 2. Expand the widget for which you want to copy a skin. 3. Select a skin, right-click, and select Copy. 4. Click Paste or Navigate to the widget for which you want to paste the skin and click Paste. 5. Enter a name for the skin in the Skin Name window. 6. Click OK. The skins view is refreshed and the skin with the new name appears under the list of skins. 7.19.16 Apply Shadows for Widgets Kony Studio allows you to apply shadows for text for the following widgets: Mobile Web/SPA HBox VBox Android/ Android Tablet Button Label iPhone/iPad Button Label Copyright © 2012 Kony, Inc. All rights reserved. Page 206 of 785 Kony Studio User Guide - 2.1 Working with Applications Mobile Web/SPA Button Label RichText Link Android/ Android Tablet iPhone/iPad RichText Text Box Text Area To apply shadows, follow these steps: 1. Go to Skins View. 2. Select any one of the above mentioned widgets. 3. Select a skin and fork it for Android or Mobile Web. 4. Go to the Shadow tab. Note: This tab appears only when you fork a skin for Android or Mobile Web. i. Enter a value for x Offset in pixels. You can enter both positive and negative value integers. ii. Enter a value for y Offset in pixels. You can enter both positive and negative value integers. The following image illustrates the co-ordinate system followed: iii. Enter a value for Blur radius in pixels. You can enter only positive values in this field. iv. Select a color for the Shadow from the Color Palette. The following pictures illustrate the shadow effect for RichText and Link widgets: Copyright © 2012 Kony, Inc. All rights reserved. Page 207 of 785 Kony Studio User Guide - 2.1 Working with Applications 7.19.17 Defining Custom CSS for Widgets You can define a custom css for widgets for Mobile Web, SPA, and Desktop Web platforms. To apply Custom CSS for a Widget, follow these steps: 1. Go to Skins View. 2. Select any widget. 3. Select a skin and fork it for Mobile Web, SPA, and Android. 4. Go to the Mobile Web CSS tab. 5. To set a Custom CSS for the Widget follow these steps: i. Select the Use Custom CSS checkbox. ii. In the text area provided, enter the properties for the CSS. A sample for a Custom CSS to be entered by the user is as follows: //Example of a Custom CSS font : normal normal 15.6px border : 1px solid #4c4c4c; background-color:white; Arial ; iii. For Segment, Label, Link, TabPane, DataGrid, and Switch widgets, you have to write the name of the class when you define the Custom CSS in the text editor. A sample for a Custom CSS to be entered by the user is as follows: //Example of a Custom CSS for Segment, Label, Link, TabPane, DataGrid, and Switch .SKINNAME{ font : normal normal 15.6px Arial ; border : 1px solid #4c4c4c; background-color:white; } These widgets have multiple classes defined in the CSS. For example for a segment, a css would have multiple classes as shown below: .SegSkinname{ } .SegSkinname grp { } .SegSkinname child 1 { } To invoke the appropriate css class for these widgets, include the class name while defining a custom css. Copyright © 2012 Kony, Inc. All rights reserved. Page 208 of 785 Working with Applications Kony Studio User Guide - 2.1 6. Click Finish. 7.19.18 ProgressIndicator When you fork a skin for Mobile Web/SPA, there is an additional tab that is available in the Edit Skin window. It is the Progress Indicator tab. This tab allows you to specify a progress indicator for a long running activity on the following widgets: l HBox l Button l Link l Segment l TextBox(Applicable only on Mobile Web). To specify details of the progress indicator, follow these steps: 1. Fork a skin for Mobile Web for any of these widgets. 2. Edit the forked skin. 3. Navigate to ProgressIndicator tab in this window. 4. Select the image that needs to appear on the ProgressIndicator and also the location of the image (left, right, or center). 7.19.19 Skin Attributes The skin background attributes vary from one widget to another widget. This section describes the various skin attributes that are available for different widgets. The following is a description of each background attribute: l Transparent - indicates that the widget background is transparent. l One Color - indicates that the widget background is represented by a single (selected) color. l Two Colors - indicates that the widget background is represented by two colors (selected) with a selected pattern (vertical gradient or vertical split). Copyright © 2012 Kony, Inc. All rights reserved. Page 209 of 785 Kony Studio User Guide - 2.1 Working with Applications l Image - indicates that the widget background is an image or a combination of images. The following table lists the applicable background styles for all the widgets in IDE: Widget Button Calendar (For more information, see Adding Skin for a Grid Calendar.) Camera Background Attribute Transparent One Color Two Colors Image Transparent One Color Transparent One Color Two Colors Image Copyright © 2012 Kony, Inc. All rights reserved. Page 210 of 785 Kony Studio User Guide - 2.1 Working with Applications Widget Background Attribute Transparent One Color The skin forked for BlackBerry has the following options in the Pattern: l normal l normal rounded l normal rounded right corners l normal rounded left corners l round tabbed Two Colors CheckBoxGroup ComboBox DataGrid Form HBox HImageStrip The skin forked for BlackBerry has the following options in the Pattern: l vertical gradient l vertical split l rounded vertical gradient l horizontal split l rounded horizontal split l rounded vertical split l horizontal gradient l centerout gradient Image Transparent One Color Image Transparent One Color Two Colors Transparent One Color Two Colors Image Transparent One Color Two Colors Transparent One Color Two Colors Copyright © 2012 Kony, Inc. All rights reserved. Page 211 of 785 Kony Studio User Guide - 2.1 Working with Applications Widget Image ImageGallery Label Line Link ListBox Phone PickerView Popup RadioButtonGroup RichText Segment Slider Tab Background Attribute Transparent One Color Two Colors Transparent One Color Two Colors Transparent One Color Transparent One Color Transparent One Color Two Colors Transparent One Color Image Transparent One Color Two Colors Image Transparent One Color Two Colors Transparent One Color Two Colors Transparent One Color Two Colors Image Transparent One Color Two Colors Transparent One Color Transparent One Color Two Colors Image Transparent One Color Two Colors Copyright © 2012 Kony, Inc. All rights reserved. Page 212 of 785 Kony Studio User Guide - 2.1 Working with Applications Widget TabPane TextArea TextBox VBox Switch AppMenu Blocked UI Background Attribute Transparent One Color Two Colors Image Transparent One Color Two Colors Transparent One Color Two Colors Image Transparent One Color Two Colors Image Transparent One Color Two Colors Image Transparent One Color Two Colors 7.19.20 Platform Specific Limitations The following is a list of platform specific limitations for skins: l iPhone supports only squared and rounded borders (plain). l J2ME and Windows Phone do not support transparency for widgets (background, font, and border). l BlackBerry supports transparency for background and borders. Transparency is not supported for Fonts. l BlackBerry does not support skin for App Menu. l BlackBerry does not support a transparent skin along with a border for the RichText widget. l iPhone and Android platforms do not support applying skins for the AppMenu items. l l iPhone supports a skin for SegmentedUI only when the groupcells property is set to false. For more information about groupcells property, see SegmentedUI in Kony Widget User Guide. iPhone does not support Font weight and style attributes for skins. Copyright © 2012 Kony, Inc. All rights reserved. Page 213 of 785 Working with Applications Kony Studio User Guide - 2.1 Mobile Web Basic Devices The following skin attributes are not supported on Mobile Web Basic devices: l Margins and Padding for all the widgets. l Transparency in font color, background color, and border colors. l Borders for Label, Link, RichText, CheckBox, and RadioButton widgets. l Focus skins for all widgets. l Rounded corners for borders for all widgets. l l l Skin with background image (dynamically) for a button. Even if you set the background image, button / button size will not be affected while the rest of the properties of the skin are affected. Underline for all widgets where the click is represented as an anchor. For example, Link, Phone, and Segmented UI. The text attributes in the skin for these widgets is set to none by default. But based on some browser limitations on some devices, the underline will still be shown irrespective of the above property. Borders with higher pixels. If you specify borders with higher number of pixels, the borders may go out of the screen depending on the layout used. In this case, you must reduce the borders. This limitation is because of the % layout used by the platform and there is no mechanism to determine the % occupied by the border in the overall screen width. On advanced devices, this issue does not arise as they use CSS layout mechanisms. The font sizes specified by the developer are mapped to the font ranges of xx-small and small. The mapping of font sizes is as follows: l If font % is < 100 then it is mapped to xx-small category. l If font % is >= 100 then it is mapped to small category. Note: These units are used because support for pt or px based font is not uniform across basic devices. Mobile Web BJS Devices The following skin attributes are not supported on Mobile Web BJS devices: l Transparency in font colors. l Focus skins for all widgets. l Rounded corners for borders for all widgets. l Vertical split and gradient for all widgets. l Borders with higher pixels.If you specify borders with higher number of pixels, the borders may go out of the screen depending on the layout used. In this case, you must reduce the borders. This limitation is because of the % layout used by the platform and there is no mechanism to determine the % occupied by the border in the overall screen width. On advanced devices, this issue does not arise as they use CSS layout mechanisms. Copyright © 2012 Kony, Inc. All rights reserved. Page 214 of 785 Working with Applications Kony Studio User Guide - 2.1 Mobile Web Advanced Devices The following are the restrictions for skin attributes for mobile Web Advanced platform: l l l In the case of form backgrounds for gradients, the gradient is applied only upto the point where the form ends. In cases where the form size is less than the screen height, a white background covers the rest of the screen. This occurs only on BB Torch & Android devices with versions prior to 2.3 versions. To overcome this problem, the developer can provide an empty hbox or vbox with padding/margin to the top and the bottom of the widget to cover the full screen size of the device. This may cause a side effect of causing the form to scroll down. Focus skin for all widgets is not supported. Windows Phone browser (IE 7 browser) does not support transparency because the RGBA property is not supported. Hence, for the widgets accessed from Mobile Web on Windows Phone, transparency for widgets (background, font, and border) is not supported. 7.20 Replacing/Copying Margins and Paddings Margins and Paddings can be applied to the widgets. l l Margin - Defines the space around a widget. You can use this option to define the top, left, right, and bottom distance between the widget and the next element. Padding - defines the space between the content of the widget and the widget boundaries. You can use this option to define the top, left, right, and bottom distance between the widget content and the widget boundary. Copyright © 2012 Kony, Inc. All rights reserved. Page 215 of 785 Working with Applications Kony Studio User Guide - 2.1 For more information about how to set margins and paddings, see Kony Widget User Guide. Kony Studio provides you an option to replace or copy the margins and paddings for the selected widget in the project at one go. 7.20.1 Replace This option allows you to replace the margins and/or paddings for the selected widget that match the given value with the specified value. To replace margins and/or paddings, follow these steps: 1. Go to Applications View. 2. Right-click the desired application and navigate and select Utilities > Margins/Paddings > Replace. Replace Margins/Paddings window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 216 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Select the Property that you want to replace. i. Select Margins. This value is selected by default. ii. Select Paddings if you want to replace both Margins and Paddings at the same time for all instances of the selected widget. Note: Selecting at least one property is a mandate. 4. Enter the values for Top, Right, Bottom, and Left for the selected property that you want to Find. 5. Enter the corresponding Replace values. 6. Select Ignore source values if you want to replace the selected property irrespective of the existing value. 7. Click Select widgets and select the required widget for which you want to replace the selected property. 8. Select the platforms on which you want to replace the selected property. 9. Click OK. The selected property is replaced with the specified values for the selected widget on the selected platforms. 7.20.2 Copy This option allows you to copy the selected property for the selected widget from one platform to one or more platforms. To copy margins and/or paddings, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 217 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Right-click the required application and select Utilities > Margins/Paddings > Copy. Copy Margins/Paddings to selected platforms window appears. 3. Select the Property that you want to Copy. i. Select Margins. This value is selected by default. ii. Select Paddings if you want to copy both Margins and Paddings at the same time for all instances of the selected widget. Note: Selecting at least one property is a mandate. 4. Click Select widgets and select the widget for which you want to copy the selected property values from one platform to another. 5. Select the source platform from the From platform drop-down list. 6. Select the destination platform(s). 7. Click OK. The values of the selected property are copied to the selected widget on the selected platforms. 7.21 Adding a Code Module to an Application A code module contains one or more functions and these functions can be used in various areas of the application as required. These code modules organize the defined functions logically. 7.21.1 Adding Code Modules The IDE provides a Lua / JavaScript syntax-aware Script Editor that is used to develop the required application client logic. The capabilities of a Script Editor include: Copyright © 2012 Kony, Inc. All rights reserved. Page 218 of 785 Working with Applications l Syntax highlighting. l Code Completion. l Code wrapping. l View listing all the user-written functions. l Code Assistance. l Syntactical checks. Kony Studio User Guide - 2.1 There is no limitation on the number of code modules in an application or the number of functions within a code module. But, it is advisable not to pack a code module with too many functions. Note: Make sure you have installed the Lua plug-in. For more information about Lua plug-in, see Kony Studio Installation Guide. 7.21.1.1 ifdef statements In the code modules when you write code specific to certain platforms, you can use the ifdef statements. You can use the ifdef statements also in the Preprocess decision in the Event Editor. When the application is built and Kony Studio generates the code for an application, all the platform names in ifdef statements are changed. For example: l iphone - m4iphone l android - m4android l blackberry - m4bb. Important: Make sure you do not use any of the following characters in the code modules: - ![ - ]! These are reserved keywords used by the M4 processor to generate the code. 7.21.2 Adding Modules for an application The IDE provides you an option to define Java Script and functions that can be executed on platforms. The Java Script functions are defined with the JS Modules. To add a JS module, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. Copyright © 2012 Kony, Inc. All rights reserved. Page 219 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Right-click js and select New JavaScript Module. 4. Specify a name for the Java Script module and click Finish. A .js file is created under the js folder. 5. For Mobile Web platforms, you can define functions for the following events: l l l l OnloadJS for form This event gets fired when the form is loaded on Mobile Web platform. This property specifies the name of the JavaScript function to be executed when a form is loaded. UnloadJS for form This event is triggered when the form is unloaded on Mobile Web platform. This property specifies the name of the Java Script function to be executed when a form is unloaded. PreEventJS for all clickable widgets This event is fired before executing the Lua module associated with the clickable widget. This property specifies the name of the javascript function to be executed after the execution of the Lua module associated with that widget. PostEventJS for all clickable widgets This event is triggered after executing the Lua module associated with the clickable widgets. This property specifies the name of the JavaScript function to be executed before the execution of the Lua module associated with that widget. 6. Define functions for each of these events. 7. Specify the name of the function that needs to be executed (when that specific event is fired) against that event in the Properties window. Note: Ensure that you do not use any of the following keywords in the code modules: - iphone - bb - winmobile - android Copyright © 2012 Kony, Inc. All rights reserved. Page 220 of 785 Working with Applications Kony Studio User Guide - 2.1 - wap - j2me - symbian - ipad - tabrcandroid. All these keywords are reserved words. Note: To comment out a code in a JavaScript module use //. 7.21.3 Sample Code for JavaScript Functions function preluafun(eventSource, sourceId){ ...try{ ...//sample ...//var domElement = new kony.dom.Element(); ...//var buttonid = sourceId; ...//var msg = "You clicked on : " +buttonid; ...//var txtLogin = domElement.getElementByIDNS("loginid"); ...//msg+="\nLogin Id: "+txtLogin.value; ...//alert(msg) ......//write your logic here ...} ...catch(e){ ...alert("Error: "+e) ...} } function postluafun(eventSource, response, sourceId){ ...//write your logic here } function formonloadfun(formId){ ...//write your logic here } function formunloadfun(formId){ ...//write your logic here } To add a Lua code module to an application, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. Copyright © 2012 Kony, Inc. All rights reserved. Page 221 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Expand modules. 4. Right-click lua and select New Module. 5. New Module window appears. Enter a name for the code module under Module Name and click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 222 of 785 Working with Applications Kony Studio User Guide - 2.1 6. The newly created code module opens in the Script Editor as shown below: Note: Every function in Lua starts with the keyword function and ends with the keyword end. 7. When writing code is complete, click (Save icon) on the toolbar to save the code module. Note: For Lua, prefix any line with -- to comment it out. Use the syntax --[[comment]]-for comments that run into multiple lines. This is used to comment out luacode only. Note: For Lua, to comment out an ifdef statement, prefix the ifdef statement line with --#. Note: Ensure that you do not use any of the following keywords in the code modules: - iphone - bb - winmobile - android - wap - j2me - symbian - ipad - tabrcandroid. All these keywords are reserved words. 7.21.3.1 Alternate Procedure 1. Launch Eclipse. 2. Open Kony Perspective. Copyright © 2012 Kony, Inc. All rights reserved. Page 223 of 785 Working with Applications Kony Studio User Guide - 2.1 3. Select File -> New -> New Lua/JS File. The New Lua File Wizard appears as shown below: 4. Enter the application's name or select an application. 5. Enter a name for the Lua code module under File name. 6. Click Finish. 7.21.4 Adding Web Modules Kony Studio allows you to create the following files right-within the IDE: l HTML files l CSS files l JS files. Note: To view these files within Kony Studio, you must download the html_js_css_editor plugin to the dropins folder of Eclipse. Restart Eclipse after you install this plug-in. To add a web module, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 224 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Navigate to Applications View. 2. Expand the required application. 3. Expand modules. 4. Right-click web modules and select Create and the appropriate file type. The supported files are HTML, CSS, and JS. 5. Enter a name for the file in the window that appears and click OK. 6. The created file opens in Eclipse. Enter the required data in the file and save it. To import a web module, follow these steps: 1. Right-click web modules and select Import Web Modules. 2. Select a zip file that has the web modules to be imported and click Open. 3. The selected zip file of web modules is imported and the zip file is extracted under the web modules folder. 4. You can access the web modules files that are imported into the application. 7.22 Forking Forms Forking forms is a useful option when you want to customize the positioning and availability of widgets on different platforms. You can use the Forking Forms option in the following scenarios: l l l to position widgets differently on different platforms when one or more widgets are to be made available on one platform and not available on another platform to replace a widget on one platform with another widget on another platform. Note: The Render property of a widget is not the same as Forking Forms. For more information about Render property, see Widget Renderer. When you fork a form for a specific platform, the original form is duplicated for that specific platform. You can modify this replicated form as per the platform requirements. To fork forms, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand forms. Copyright © 2012 Kony, Inc. All rights reserved. Page 225 of 785 Working with Applications Kony Studio User Guide - 2.1 4. Right-click the form you want to fork and select Fork. 5. Fork window appears as shown below. Select the platforms for which you want to fork the selected form. Note: In this window, you can select only the platforms on which the form was not forked. 6. Click Finish. The forked form appears as shown below in the Applications view under forms. 7. Select the required form to modify it. 7.23 Forking Headers and Footers When you want different application headers/footers to be applied on different platforms, you need the option to fork the headers/footers. The procedure given below explains how to fork an application header. You can follow similar steps to fork an application footer. To fork headers, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 226 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Select and expand the required application. 3. Expand headers and select the header which you want to fork. 4. Right-click the selected header and select Fork. The Platform selection window appears as shown below: 5. Select the platforms on which you want to fork the header and click OK. 6. The forked header appears under headers as shown below: 7. Double-click the forked header to open it. Copyright © 2012 Kony, Inc. All rights reserved. Page 227 of 785 Working with Applications Kony Studio User Guide - 2.1 8. Make the required changes to the header once it is open in the Form Designer. Note: Ensure that you do not use any of the following keywords in the forked headers and footers: - iphone - bb - winmobile - android - wap - j2me - symbian - ipad - tabrcandroid. All these keywords are reserved words in Lua. 9. Save the changes. 7.24 Configuring Widget Property Defaults This section explains how to configure the default transition effects for all the forms at a project level. The transition effects specify the type of transition effect to be applied when the Form appears in the view. Note: These transition effects are applicable only on Windows Phone 7. The transition effects specified at the form level (if any) override the project level default values. To configure the transition effects for the forms at the project level, follow these steps: 1. Go to Applications View. 2. Select the required application. 3. Right-click and select Widget Property Defaults. 4. Select appropriate values for In Transition, Out Transition, In/Out Transition mode, and Animate headers, footers. The possible values for these transition effects are explained below: Copyright © 2012 Kony, Inc. All rights reserved. Page 228 of 785 Kony Studio User Guide - 2.1 Working with Applications Transition Effect Value Rotate3DSingle Rotate3DDual In Transition Slide Popup Squeeze Value Rotate3DSingle Rotate3DDual Out Transition Slide Popup Squeeze Value Sequential In/Out Transition mode Parallel Possible Values Description Specifies that the Form must be rotated along the center Y-Axis when coming into the view. Specifies that the Form must be shown making a circle around the screen from the background before coming into the view. Specifies that the Form must slide horizontally into the view. Specifies that the Form must emerge from center-bottom of the screen and gradually occupy the complete screen. Specifies that the Form must be expanded horizontally from an initial width of zero. Description Specifies that the Form must be rotated along the center Y-Axis when going away from the view. Specifies that the Form must be shown making a circle into the screen from the foreground before going out of view. Specifies that the Form must slide away from the view. Specifies that the Form must disappear into the center-bottom of the screen. Specifies that the Form must be squeezed from the sides to the center and go out of view. Description The transition of the Form going out of the view completes first and then the transition of the Form coming into the view takes place. The transition of the Form going out of the view and the transition of the Form coming into the view takes place simultaneously. Copyright © 2012 Kony, Inc. All rights reserved. Page 229 of 785 Kony Studio User Guide - 2.1 Working with Applications Transition Effect Value Possible Values Description Specifies that the headers and footers of the Form must slide up and down respectively away from the view when the Form is in transition. true Note: The headers and footers will animate only if the headers and footers of the transitioning Forms are different and have the property set to true. Animate headers, footers false Specifies that the headers and footers of the Form must not slide up and down respectively away from the view when the Form is in transition. 7.25 Configuring Project Properties Project properties are the various properties that are to be set for the application. The properties are listed below: l Application Properties l Kony Server Properties l Build Properties l App Settings l Splash Screen (Native App) Properties l Mobile Web Properties l Desktop Web Properties l Push Notifications l Native App Properties. Note: Setting all these properties is a prerequisite for building the application you have developed. For Mobile Web applications, Kony Studio provides you with an option to select the mode (secure/unsecure) in which data in the forms is transmitted to the server. Right-click the application and select Utilities > Change/Replace property > Make All Form Submit > Secure or UnSecure based on the requirement of the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 230 of 785 Working with Applications Kony Studio User Guide - 2.1 The form property Secure Submit specific to Mobile Web is overridden by the value you select here. For more information about this property, see Kony Widget User Guide. 7.25.1 Launching Project Properties Before you proceed with configuring various Project Properties, you must launch the Project Properties window first. To launch project properties window, follow these steps: 1. Go to Applications view. 2. Right-click the application for which you want to set properties and select Properties. 3. The Project Properties window appears . 7.25.2 Application Properties Application properties are specific to the application. These are the properties like application ID, version, name, and company name. The pre-appinit, appinit, and post-appinit events are also specified here (if required). l pre-appinit is the event that needs to be executed before initializing the application (before loading the application. Note: You can also define an action sequence for the pre-appinit event to dynamically define an App Menu. l appinit is the event that needs to be executed at the time of initializing the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 231 of 785 Working with Applications l l Kony Studio User Guide - 2.1 post-appinit is the event that needs to be executed after initializing the application but before showing any data. For example, you can write the logic for displaying the TermsAndConditions form in this event. App-service is the event that allows you to launch and deeplink Kony native applications from any third-party native application and browser application. This feature allows better integration of Kony applications (all native & Mixed Mode applications) with other native and browser based applications. For more information refer App Service. You can define all these events or action sequences using the Event Editor. To set application properties, follow these steps: 1. Go to Project Properties window. 2. Click Application tab. ID, Version, Company Name fields are automatically populated based on the application you select. You can change these values if required. 3. 4. Define App Life Cycle Events. i. Define action sequences for pre-appinit and post-appinit events separately for Mobile platform and Tablet platform. These are optional and you can define action sequences in the Event Editor for these App Life Cycle Events. ii. Define an action sequence for Deeplink Function. Deeplink enables you to navigate to any form of the mobile application rather than the normal start up form. For more information, see Deeplink Function. Note: Deeplink Function is applicable only for Mobile Web. Copyright © 2012 Kony, Inc. All rights reserved. Page 232 of 785 Working with Applications Kony Studio User Guide - 2.1 5. Enter a value for a key in the all the Map widget key fields. This key needs to generated. For more information about map key and generating it, see Generating and Configuring Map APIs Keys. 6. Click Finish. 7.25.3 Kony Server Properties The properties related to Kony Server are set in this window. The properties you specify here are taken into consideration while: l publishing the application l publishing services. To set Kony server properties, follow these steps: 1. Go to Project Properties window. 2. Click Kony Server tab. 3. Enter the Server Details. i. Enter the Server Name/IP Address in URL. This field denotes the place to which the application will be published. ii. Enter a port number for Http Port. If you do not specify a port number, the default port number, 80, is used. iii. Enter a port number for Https Port. If you do not specify a port number, the default port number 443 is used. Copyright © 2012 Kony, Inc. All rights reserved. Page 233 of 785 Working with Applications Kony Studio User Guide - 2.1 4. Enter the Web Context. Web Context is the string that identifies the application on Kony Application Server. i. Enter web context for Mobile Web. Context is the string that identifies the application to be launched on the server. It must start with an alphabet and contain alphanumeric characters. For example, https://konylabs.net/mobile23/. In this case https://konylabs.net is the server name and mobile23 is the context. Note: It is compulsory to provide a web context for mobile web applications. ii. Enter the Middleware Context. Context is the string that identifies the application on Kony Application Server. Note: If no context is specified, middleware is used as the context. 5. Enter Basic Authentication Details (Native Apps only). If the server to which the application or service has to be published requires authentication, the username and password entered in this area enables you to view the contents on the server directly. i. Enter the User ID to access the server. ii. Enter the Password for authentication to the server. 6. Click Finish. 7.25.4 Build Properties Build properties need to be set as a prerequisite before building an application. These properties define the way an application is built and also the behavior of the application on the actual mobile device. To set build properties, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 234 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Project Properties window. 2. Click Build tab. 3. Select release from the drop-down list under Build. The application should be in release mode to build it successfully and to make it ready for release. Note: If you want to debug the application, change the mode to debug in the drop-down list. 4. Check Remove print statements in custom modules (Recommended setting for production release). This option when selected removes the print statements, which were added while debugging, from the application. 5. Retain the other values as is. These are the recommended settings. 6. Select Use MDS for Blackberry Mobile Native App to enable the device for wireless connectivity. For more information about BlackBerry MDS, see the Appendix: BlackBerry MDS. 7. Click Finish. 7.25.5 Splash Screen (Native App) Properties These properties define the splash screen properties. Note: Splash Screen properties are applicable only on Native App, SPA, and Desktop Web. Splash Screen is the initial screen that appears when you launch an application. To set splash screen properties, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 235 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Project Properties window. 2. Click Splash Screen (Native App, SPA, Desktop Web) tab. 3. Select the Background Color and Foreground Color for the splash screen.Application Launch Mode. Important: Background and Foreground color are not supported on iOS and versions previous to Windows 8. 4. Select your desired device to Show loading indicator in the application. This property is applicable only on iPhone and Android platforms. 5. Choose your orientation Mode as Portrait or Landscape, and select a Splash Image or a Splash Video. The following formats are supported for images: l png l jpg l jpeg Copyright © 2012 Kony, Inc. All rights reserved. Page 236 of 785 Kony Studio User Guide - 2.1 Working with Applications l gif Note: Android and iOS devices do not support gif file. The following formats are supported for videos: l mp4 l mov l m4v l mjpeg l avi. Note: Splash videos are not supported on Desktop Web and Windows. The splash screen image sizes are provided in the following table: Device iOS (iPad) (PNG recommended) iOS (iPhone) (PNG recommended) Android (9-Patch PNG recommended) Mode Resolution Non-Retina (1x) - Portrait 768 x 1004 px Non-Retina (1x) - Landscape 1024 x 748 px Retina (2x) - Portrait 1536 x 2008 px Retina (2x) - Landscape 2048 x 1496 px Non-Retina (1x) - Portrait 320 x 480 px Non-Retina (1x) - Landscape 480 x 320 px Retina (2x) - Portrait 640 x 960 px Retina (2x) - Landscape 960 x 640 px iPhone 5 Retina (2x) - Portrait 640 x 1136 px iPhone 5 Retina (2x) Landscape 1136 x 640 px LDPI - Portrait 200 x 320 px LDPI - Landscape 320 x 200 px MDPI - Portrait 320 x 480 px MDPI - Landscape 480 x 320 px HDPI - Portrait 480 x 800 px HDPI - Landscape 800 x 480 px XHDPI - Portrait 720 x 1280 px XHDPI - Landscape 1280 x 720 px BlackBerry (PNG recommended) Any image size can be used.. It should be smaller than your smallest screen size. Windows Phone (JPG recommended) Portrait 480 x 800 px Landscape Not supported Copyright © 2012 Kony, Inc. All rights reserved. Page 237 of 785 Working with Applications Kony Studio User Guide - 2.1 For more information about the size of images and guidelines, refer the following links: l l iPhone and iPad, see https://developer.apple.com/library/ios/documentation/userexperience/conceptual/mobilehig/L aunchImages.html. Android, see http://developer.android.com/guide/practices/screens_support.html#testing. Important: When you specify the splash screen images for BlackBerry 7.0, you must create folders that correspond to the device dimension (within the \resources\mobilerichclient\blackberry folder) and place images within the respective folders. Important: When you specify a splash screen image for Android , you must set an orientation as portrait or landscape in the Android Native tab. Additionally add an image by the same name by navigating to resources > mobilerichclient> android. Right click Android and select Add Resource Folders. Set the desired Screen Orientation and click OK. Add required images under the newly created folder. 6. Select if the video can be interrupted using Video Interpretable check box. 7. Specify the Animation Duration is seconds. 8. Select and load the Progress Bar Animation Images. Note: The images specified for Progress Bar are displayed one after the other. These images are overlaid on the splash screen. This gives an animation affect to the user launching the application. You can select the required number of images that you want to be a part of the Progress Bar. Progress Bar animation is not supported on Windows, Mobile Web and Desktop Web. 9. Select if the video can be interrupted using Video Interpretable check box. 10. Specify a number for the Animation Duration (in seconds). Each progress bar image you specify appears on the screen for the specified number of seconds. 11. Specify the Progress Bar Animation Images by clicking the Add button. Browse and select to add each progress bar animation image. Note: The images you specify as the progress bar animation images must be present in the resources folder of the project. Note: There is no restriction on the number of images you can specify. Important: Ensure that the same name is used for the images on all platforms. If you do not specify a platform specific image, the image specified in the Default tab is used. 12. Click Finish. Splash Screen Properties for iPhone 5 Copyright © 2012 Kony, Inc. All rights reserved. Page 238 of 785 Working with Applications Kony Studio User Guide - 2.1 The application built for iPhone5 will run in only compatibility mode if there is no 1136x640 Default.png splash screen configured. Configuring this new splash screen image would make the application run in full screen mode. This new splash screen image must be called as [email protected]. Presence of this new splash screen image file ([email protected]) in image resources in Kony IDE ensures that your application on iPhone 5 will run in full screen mode.. Essentially you will have to include this new splash screen image file in the resources folder in Kony IDE and clean & rebuild the iPhone app. You can configure the Image which is of the following dimension:1136 x 640 as the new splash screen image but for testing purposes you can make a copy of your existing launch splash screen and rename it as [email protected]. Please note that [email protected] is required in addition to your existing splash screen image . 7.25.6 Mobile Web Properties Mobile Web is the browser on the device. Mobile Web properties define the properties for the application on Mobile Web under various platforms. To set Mobile Web properties, follow these steps: 1. Go to Project Properties window. 2. Click Mobile Web tab. 3. Browse and select the appropriate Shortcut icons for iPhone . When you launch the application on iPhone you see the icon specified here as the application icon. 4. Browse and select the appropriate fav icons for Web Browser. When you launch the application on Web Browser you see the icon specified here as the application icon. Copyright © 2012 Kony, Inc. All rights reserved. Page 239 of 785 Kony Studio User Guide - 2.1 Working with Applications 5. Enter a Title for the application. This title appears on the web browser when you launch the application on Mobile Web. 6. Navigate to the General tab. i. Select the appropriate Session Manager in Session Management. Session management indicates how session data (for example, user name and password) is managed. Kony Session Manager indicates that the data is stored on the Kony Application Server and Http Session Manager indicates that the data is stored as part of the session object. ii. Select Phone format Indicator if you want to highlight a telephone number clearly in the browser. iii. Select Requires GPS functionality to enable the application to use the GPS functionality. For more information about GPS functionality, see the appendix GPS Functionality. iv. Select Enable focus skin for HTML5 iPhone and BlackBerry, to enable focus skins for HTML5 iPhone and Blackberry. v. Select Enable Server side Mobile Web in Build Screen, to build applications for the Server side Mobile Web platform. vi. Under No Java Script message, enter a message to be displayed to the user if the browser does not support Java Script. the default message is To use this site, first enable your browser's JavaScript support and then refresh this page. If you want to display a different message, overwrite this message. 7. Navigate to Base Fonts tab. i. Select appropriate Base Font sizes in points for iPhone and various categories of browsers. Note: When you specify the font size within the skin of a widget, the font size is calculated based on this Base Font. The following table explains the base fonts for each platform: Platform iPhone BlackBerry 240 BlackBerry 320 BlackBerry 480 Basic Devices Basic with JS 240 Basic with JS 320 Base Font (in points) 12 12 15 17 10 10 10 Copyright © 2012 Kony, Inc. All rights reserved. Page 240 of 785 Kony Studio User Guide - 2.1 Working with Applications Platform Basic with JS 480 Android 240 Android 320 Android 480 Android 640 Palm 240 Palm 320 Palm 480 SPA iPad SPA Android Tablet Base Font (in points) 10 10 10 14 19 10 12 14 17 17 8. Navigate to App Menu More Image tab. i. On platforms like iPhone, BlackBerry, Android, Palm, XHTML BJS, and XHTML More button appears when the app menu has more than 5 app menu items. You can specify an image for the More button on these platforms. Browse and select the image if you an image to displayed instead of the standard More button. Note: If you do not specify an image, the standard More button is displayed. 9. Navigate to Site Minder tab. i. Add a Context ID. Context ID is used to set the context path in the URL of an application. ii. Add a corresponding Context Path. Context Path appears in the application URL. 10. Navigate to Import JS tab. i. Click the Add button to add a row where you can specify the URL of the Java Script file that you want to be executed in the browser. Copyright © 2012 Kony, Inc. All rights reserved. Page 241 of 785 Working with Applications Kony Studio User Guide - 2.1 ii. Repeat the above step if you want add more Java Script files. 11. Navigate to Mixed Mode Server Details tab. Provide the details of the server that must be used for a Mixed Mode application. Use this option to set default image while downloading the image if you do not have any image for image while loading property. 12. You can specify a default downloading image under the SPA tab which is displayed to the user instead of a blank page. 13. Click Finish. 7.25.7 Desktop Web Properties Desktop Web is the browser of the desktop . Desktop Web properties specify the properties for the application on Desktop Web under various platforms. To set Desktop Web properties, follow these steps: 1. Go to Project Properties window. 2. Click Desktop tab. 3. Browse and select the appropriate fav icons for Desktop Web Browser. When you launch the application on the Desktop Web Browser you see the icon specified here as the application icon. 4. Enter a Title for the application. This title appears on the web browser when you launch the application on Mobile Web. 5. Navigate to the General tab. 6. From the Base Fonts list, select the appropriate base font size in pixels. i. Select appropriate Base Font sizes in points for iPhone and various categories of browsers. Note: When you specify the font size within the skin of a widget, the font size is calculated based on this Base Font. 7. In the Screen Width field, specify the width the application occupies in the Desktop Web browser. The screen width value can be percentage based or pixel based. 8. From the Alignment list, select how the application is aligned in the browser. The possible values are center, left, and right. Copyright © 2012 Kony, Inc. All rights reserved. Page 242 of 785 Working with Applications Kony Studio User Guide - 2.1 7.25.8 Windows 8 Properties Each application for Windows 8 is displayed as a Live tile on the Main page, as an icon on the application list, and appears on the Search Charm menu as well. The Windows 8 properties will be applied to the form created under the tablet section. Setting Application UI Properties l Under the Application UI tab enter the following: o Display name: The display name of the application visible in the search charm or in the applications list. o Description: Specifies the description to be displayed on the tile. For example a tile on finance can contain a generic description about stocks. o Logo: Browse for the image to be displayed on the tile when the tile size is a square block. o Wide Logo: Browse for the image to be displayed on the tile when the tile size is a wide rectangular block. o Small Logo: Browse for the image to be displayed when the application is viewed in the search charm or the applications list. o Short name: Specifies the short name displayed directly on the tile. Anything over 40 characters will be truncated. The user has the option to change this value as part of the pinning process. o Show name: Specifies whether the short name is to displayed for certain tile types o Tile Foreground Text: Specifies the color of the text to be displayed on the tile. Light indicates the color of the text as white. Dark indicates the color of the text to be black o Tile Background Color: Specifies the background color of the application tile. Copyright © 2012 Kony, Inc. All rights reserved. Page 243 of 785 Working with Applications o Splash screen: Specifies the splash screen image to be displayed. Splash Screen is the initial screen that appears when you launch an application. o o Kony Studio User Guide - 2.1 The following formats are supported for images:png, jpg, jpeg, and gif. The image you specify as the splash screen image must be present in the resources folder of the project. Background color: Specifies the background color to be used for the Splash Screen. Setting Capabilities Using the capabilities tab you can: Enable or disable permissions for the Windows 8 application using this pane. For more information about each of the permissions refer Using the Manifest Designer. i. To enable permissions, select the permissions that are currently false and click Add >. ii. To disable permissions, select the permissions that are currently true and click < Remove. Setting Packaging attributes Copyright © 2012 Kony, Inc. All rights reserved. Page 244 of 785 Kony Studio User Guide - 2.1 Working with Applications Using the packaging attributes, you can set how the executable built using Kony Studio will be displayed in the application. Under the Packaging tab, enter the following: l l l Package name: Internal name of the executable package when built. You cannot enter special characters and spaces in this field. Package display name: Package name to be displayed on the Windows App store. Publisher name: Internal name of the publisher when the executable is built. You cannot enter special characters and spaces in this field. l Publisher displayname: Name of the Publisher to be displayed on the Windows App store. l Logo: Browse for the logo of the application to be displayed on the Windows App store. l Version: Version of the Package built. l Certificate file: If publisher name is other than Kony, App developers must pass a certificate whose "Issuers Name" matches with the publisher name. App developers can pass a pre created certificate file or they can create a certificate file from IDE. Note: You can create a certificate from IDE only when makecer.exe exists in the system. To view the package details, launch the application and navigate to the Settings Charm of the Application. Setting a Sequence for the Application An application developed for Windows 8 supports sequences (Normal and Flip Views) to present information to the user. These views govern the way information is displayed to the user. l l Normal View places individual forms horizontally next to each other in and manages left and right navigation. The first form and a partial portion of the next form of the application is visible Flip View enables you to flip through the forms of the application and displays only one form at a time. Flip View l l l Normal View Splits the screen and creates panels that can be viewed one at a time Scrolls horizontally Used to present information divided into several subsets l l Displays complete content of one form and partial content of another form Scrolls horizontally Copyright © 2012 Kony, Inc. All rights reserved. Page 245 of 785 Working with Applications Kony Studio User Guide - 2.1 Kony Studio provides you an option to define the forms that need to be included in the Flip Views or Normal Views. Based on the content in the forms, you can decide to include the forms either in Flip View or Normal View. The guidelines for using Flip view are available at Guidelines. To define a normal view, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Properties. The Application Properties dialog appears. 3. Under the Native Application Tab, click the Windows 8 subtab. 4. Right-click Normal Views and select Add Normal View or select Normal View and click the Add ( button. ) 5. A normal view is created with a unique ID. i. In the properties area, select the General tab and execute the following steps: a. The ID is automatically created. Modify the ID if required. Note: The ID of each normal view in an application must be unique. b. Enter a Title for the Normal View. c. Select the i18n Key for the Title, if required. d. Select a Skin for the Normal View. If you do not specify a skin, Kony default skin is applied. Copyright © 2012 Kony, Inc. All rights reserved. Page 246 of 785 Kony Studio User Guide - 2.1 Working with Applications e. Select the Header that must be used for the Normal View. If you do not specify a header, then no header is applied to the Normal View. Note: The header and footers of the form(s) within the sequence will remain intact. f. Select the Footer that must be used for the Normal View. If you do not specify a footer, then no footer is applied to the Normal View. g. Select Show app level headers, footers to indicate if the global headers and footers of the form (s) within the sequence must be displayed. ii. Click the Add ( ) button in the bottom pane to add a row to the table. a. Provide a Title for the form. b. Select a Form to be included in the Normal View. c. Select the i18n Key for the Form Title. Important: One form can be included only in one Sequence (normal or flip). Using the same form in multiple sequences throws an error. Important: At least one form must be included in the Normal View to enable the Finish button. 6. Repeat steps 4 and 5 to add more Normal Views. 7. Click Finish. To define a Flip view, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Properties. The Application Properties dialog appears. 3. Under the Native Application Tab, click the Windows 8 subtab. 4. Right-click Flip Views and select Add Flip View or select Flip View and click the Add ( ) button. Copyright © 2012 Kony, Inc. All rights reserved. Page 247 of 785 Kony Studio User Guide - 2.1 Working with Applications 5. A Flip view is created with a unique ID. i. In the properties area, select the General tab and execute the following steps: a. The ID is automatically created. Modify the ID if required. Note: The ID of each panorama view in an application must be unique. b. Enter a Title for the Flip View. c. Select the i18n Key for the Title, if required. d. Select a Skin for the Flip View. If you do not specify a skin, Kony default skin is applied. e. Select the Header that must be used for the Flip View. If you do not specify a header, then no header is applied to the Flip View. Note: The header and footers of the form (s) within the sequence will remain intact. f. Select the Footer that must be used for the Flip View. If you do not specify a footer, then no footer is applied to the Flip View. g. Select Show app level headers, footers to indicate if the global headers and footers of the form (s) within the sequence must be displayed. ii. Click the Add ( ) button in the bottom pane to add a row to the table. a. Provide a Title for the form. b. Select a Form to be included in the Flip View. c. Select the i18n Key for the Form Title. Copyright © 2012 Kony, Inc. All rights reserved. Page 248 of 785 Working with Applications Kony Studio User Guide - 2.1 Important: One form can be included only in one Sequence (normal or flip). Using the same form in multiple sequences throws an error. Important: At least one form must be included in the Normal View to enable the Finish button. 6. Repeat steps 4 and 5 to add more Flip Views. 7. Click Finish. Using Sequences After you have defined the Flip Views and Normal Views and included the necessary forms, you can use these views anywhere in the application based on your requirement. For example, if frmA is included in a Normal View along with few other forms, you can use that Normal View by using the following code: form.show (frmA); The whole Normal View is displayed with frmA highlighted. You can use a Flip View in the similar way. Important Considerations The following are a few implementation details about the Views within an application: l l Form methods like preshow and postshow are executed when the form is highlighted in the Pivot View or Panorama View Events like transactionaldataload and masterdataload are executed when the form is shown for the first time in the Pivot View or Panorama View. Limitations The following are the limitations of sequences in Windows 8: l l Once a form is included in a sequence, it cannot be re-used in any other sequence. A form that is included in a sequence cannot be accessed directly. You can access it only through a sequence. Setting events in the Charms tab Using the Charms tab you can define events when the view state of the application changes or when the Search Charm is invoked. Onview Change Copyright © 2012 Kony, Inc. All rights reserved. Page 249 of 785 Working with Applications Kony Studio User Guide - 2.1 The Onview State Change button enables you to add an event when the application view state changes. In Windows 8 there are 4 possible view states for the application: FullScreenLandscape, Filled, Snapped, FullScreenPortrait. The app developer can specify an action sequence in the IDE, which will be executed when the view state of the application changes. The view state of the application changes based on the end user's discretion. A user might have the application snapped to the side of the desktop monitor, or the application might fill the whole screen of a tablet. Using the Onview State Change button you can define a series of events or an alert to be displayed to the end user when the view state of the application is changed. For more information about defining Action sequences refer Defining an Action Sequence. For example, in the Onview State Change event, you can set the form to be displayed to the end-user when the view state of the application is changed. You can define a separate form for each view state. Copyright © 2012 Kony, Inc. All rights reserved. Page 250 of 785 Working with Applications Kony Studio User Guide - 2.1 UseCase The event object prevState and currState refer to the previous state and the current state of the form respectively. You can assign it to a variable as shown in the snippet below: //_viewstate is a variable declared _viewstate = currState; //_prestate is a variable declared _prestate = prevState; alert("i am in onview state change function"); showForm(); You can show the form to be displayed based on the view state of the form: function showForm() { alert(_viewstate); alert(_prestate); switch (_viewstate) { case constants.VIEW_STATE_SNAPPED: frmSnapped.show(); Copyright © 2012 Kony, Inc. All rights reserved. Page 251 of 785 Working with Applications Kony Studio User Guide - 2.1 break; case constants.VIEW_STATE_FILLED: frmFilled.show(); break; case constants.VIEW_STATE_FULLSCREEN_LANDSCAPE: frmLandscape.show(); break; case constants.VIEW_STATE_FULLSCREEN_PORTRAIT: frmPortrait.show(); break; default: frmHome.show(); break; } } On Search You can use the Search charm to open a search pane where you can enter search queries and enable your application to display their search results. To add a search charm to your application you must have a Search contract. For more information on the Search Charm refer Guidelines. The app developer can specify an action sequence in the IDE, which is executed when the user performs a search on the application using a Search Charm . The query string with which the user is trying to search in the application, is available as a parameter to the action sequence. For example if the user is trying to search the word Kony. The query entered by the user is available as an Event Object in the IDE. Copyright © 2012 Kony, Inc. All rights reserved. Page 252 of 785 Working with Applications Kony Studio User Guide - 2.1 You can create a search query such that when query=Kony, form.show(form1); For more information about defining Action sequences refer Defining an Action Sequence. Charm Settings The Charm settings on the Windows 8 platform contains settings that you can apply to the application. The settings can be configured to control an application's access to system capabilities and some specific settings of the current application. To view the Charm settings pane, swipe from the right side of the screen from right to left. For more information about Charm settings, refer Charm Settings. Copyright © 2012 Kony, Inc. All rights reserved. Page 253 of 785 Working with Applications Kony Studio User Guide - 2.1 Apart from using the Charm APIs, you can set charm menu items using the window below. Copyright © 2012 Kony, Inc. All rights reserved. Page 254 of 785 Working with Applications Kony Studio User Guide - 2.1 ID: Specifies the identifier of the Charm menu item being created. If a Charm menu item is already created with the identifier passed, a new Charm setting menu item will be created and the old Charm setting menu will be replaced with the new one. At least one menu item must be present in the Charm settings menu created. A Charm settings menu with no menu items is invalid. Title: Specifies the title of the charm menu item. Possible examples for charm menu items are Help, About,or Options as depicted in the figure above. Event: Specifies the event to be invoked when the user clicks the charm menu item. For more information about defining an event, refer Action Sequences. When you create a charm menu from IDE, by default the menu name is charmsluasettingsMenu for Lua and charmsjSettingsMenu for JavaScript projects. 7.25.9 Push Properties This tab allows you to specify a user-defined function that registers the application for Push Notifications. To set push notification properties, follow these steps: 1. Go to Project Properties window. 2. Click Push Notifications tab. 3. Select an appropriate function that registers the application for Push Notifications and enables push notifications. 4. Click Finish. 7.25.10 Native App Properties Native App properties relate more to the Application Menu on Native App. You can specify a name and logo for the App menu on Native App. Copyright © 2012 Kony, Inc. All rights reserved. Page 255 of 785 Working with Applications Kony Studio User Guide - 2.1 To set Native App properties, follow these steps: 1. Go to Project Properties window. 2. Click Native App tab. 3. Under the Common tab, set the following properties: a. Enter a Name for the application on Native App. If no name is specified, the name specified under Application Properties is taken into consideration. b. Browse and select a Logo for the App Menu on Mobile Native App. Important: l l The logo you specify here will be renamed to icon.png while building the application on iPhone platform. For Desktop / Kiosk, the icon dimension must be in multiples of 8. Minimum pixels can be 8 x 8 and maximum pixels can be 248 x 248. 4. Under Android tab, set the following properties: a. In Supported Screens section: l Any Density - If this option is enabled, the application can accommodate any screen density for a resource. You do not have to use this option if your app directly manipulates Copyright © 2012 Kony, Inc. All rights reserved. Page 256 of 785 Working with Applications Kony Studio User Guide - 2.1 bitmaps. Generally this option must always be set to true. l l l l l Small Screens - If this option is enabled, the application supports smaller screen formfactors. A small screen is one with a smaller aspect ratio than the normal (traditional HVGA) screen. An application that does not support small screens is not available for small screen devices from external services (such as Google Play). Normal Screens - If this option is enabled, the application supports normal screen formfactors. Traditionally, this is an HVGA medium density screen, but WQVGA low density and WVGA high density are also considered to be normal. Large Screens - If this option is enabled, the application supports larger screen formfactors. A large screen is defined as a screen that is significantly larger than a "normal" handset screen, and thus might require some special care on the application's part to make good use of it, though it may rely on resizing by the system to fill the screen. If the option is unchecked, this option will generally enable screen compatibility mode. Extra Large Screens - If this option is enabled, the application supports extra large screen form-factors. An extra large screen is defined as a screen that is significantly larger than a large screen, for example tablet (or something larger) and may require special care on the application's part to make good use of it. Though, it may rely on resizing by the system to fill the screen. If the option is unchecked, this will generally enable screen compatibility mode. Resizable - If this option is enabled, the application is resizable for different screen sizes. This property is deprecated by Android SDK and is supported only for customers on the 2.6 plug-in. This property enables you to run an application in the compatibility mode. For more information, refer http://developer.android.com/guide/topics/manifest/supports-screens-element.html. b. In SDK Versions section: l l Select the Minimum SDK Version that needs to be supported for the application. Default value is 1.6. This default value is applicable only for the applications created using Kony Studio. Select the Target SDK Version that needs to be supported for the application. Note: The Target SDK Version must be greater than or equal to the Minimum SDK Version. l Select the Maximum SDK Version that needs to be supported for the application. c. Package Name. This is the name with which the application is submitted to Android Market. Android Market is an online software store developed by Google for Android mobile devices. A software program called Market is pre-installed on most of Android mobile devices. This software allows the users to browse and download third-party applications. This name is used to search the application in Android Market. Note: The name you specify for Android Package must contain at least two segments. A segment is a valid Java package name. The following are a few examples of valid Android Package names: Copyright © 2012 Kony, Inc. All rights reserved. Page 257 of 785 Kony Studio User Guide - 2.1 Working with Applications l com.konylabs.<ApplicationName> l com.kony.<ApplicationName> l com.konysolutions.<ApplicationName> l com.kony.<ApplicationName>_Android. d. Version Code. This is an internal version number. This number is used to determine whether the application is a recent version. This version number is not shown to users. The value must be set as an integer. You can increase each version by one to indicate as a newer version. e. In Push Notifications section: l GCM - Select this option to enable Push Notifications for the application. This option copies the libraries required for push notification into the project during build time. Important: GCM (Google Cloud Messaging) is supported only for Android SDK Versions 2.3 and above. l Custom GCM Broadcast Receiver (Optional) - If your application requires to override the default GCM broadcast receiver behavior, you can provide your own custom broadcast receiver. To customize GCM receiver, Customizing GCM Broadcast Receiver. f. In Miscellaneous section: l l Enable Charts - To enable the Charts feature. Allow Self Signed/Untrusted Certificates - Used to control the Certificates that are used. o None - No certificates are allowed. o All - All type of certificates are allowed irrespective of whether they are bundled or not. o Allow Bundled - Only the certificates which are bundled along with the application is allowed. To bundle the certificate in the application, copy the certificate under the following folder: <workspace>/<app>/resources/mobile/native/andr oid/assets/certs Note: If assets folder does not exist, create assets folder under the following location: <workspace>/<app>/resources/mobile/native/and roid/ and create certs directory under the assets folder. Add all the certificates into certs folder. g. In Install Location section: l Use Location Preference. This property defines the location where the application is deployed. Copyright © 2012 Kony, Inc. All rights reserved. Page 258 of 785 Kony Studio User Guide - 2.1 Working with Applications o Auto - indicates that the application is deployed on the device and can be moved to SD Card later if required. o Prefer SD Card - implies that the application is deployed on the storage card and cannot be moved to the device memory at a later point of time. Note: This works only if the Minimum SDK is 2.3 or above. h. Splash Screen Orientation Mode - When resource folders are created from IDE by Add resource folders option, then directories like “drawable-port”, “drawable-land” are created automatically inside the directory <workspace>/<app>/resources/mobile/native/android. l l l Portrait - Use this option if splash screen support is required only for portrait mode and copy it inside drawable-port folder. Landscape - Use this option if splash screen support is required only for landscape mode and copy it inside drawable-land folder. Both - Use this option if splash screen support is required for both modes and both are different images then place it in respective directories. If you use same image for both modes, then copy the resources under mobile->native-> android instead of drawable-port or drawable-land folder. i. ActionBar - Enabled only if target SDK is 3.0 or above. Use this option to enable Action Bar feature. j. Support x86 Devices - Select this option to support any Android-x86 devices. For more information on devices, see the http://www.android-x86.org/hardware-list. k. In Manifest Properties section: l Permissions tab: Set the permissions to true or false based on the application requirements. Set the appropriate permissions for Android Manifest file. For more information, see AndroidManifest File. i. To enable permissions, select the permissions from the left pane and click Add >. ii. To disable permissions, select the permissions from the right pane and click < Copyright © 2012 Kony, Inc. All rights reserved. Page 259 of 785 Kony Studio User Guide - 2.1 Working with Applications Remove. l l Tags tab:. You can add tags to the Android manifest file directly from Kony Studio using Child tag entries under<manifest> tag area and Child tag entries under <application> tag area. For more information on the tags you can add with the manifest or application tags refer http://developer.android.com/guide/topics/manifest/manifest-intro.html. Deeplink URL Scheme tab: You can use the URL Scheme tab for Deeplinking. The values for Scheme/ port/ path/host/pathprefix/path pattern specified under this tab can be used to deeplink to a particular URL directly. For instance, if you set the masterdata for a browser widget to be a URL to deeplink, use the following format, scheme://host:port/pathorpathPrefixorpathPattern. For more information on each of the values available under the URL Scheme tab, refer http://developer.android.com/guide/topics/manifest/data-element.html#path. Important: For URL scheme in Android, please note that the scheme name should be in lower caps otherwise it will not work in higher versions (Android 4.0 and above) or Android devices. 5. Under iPhone/iPad tab, set the following properties: a. Bundle Identifier - a unique name that identifies the application bundle. This is usually in three parts and follows the convention of com.kony.<appname> . b. Bundle Version - a number that identifies the version of the application bundle. c. Apply Glossy Effect to App Icon - specifies if the glossy effect must be applied to the app icon. The default value is false. d. Application Launch Mode for iPad - specifies the default mode of launching the application on iPad. Portrait is the default value. e. Supported Orientations for iPad - specifies the supported orientations for the iPad. This depends on the launch mode. The different orientations for a form and at application level are listed at Copyright © 2012 Kony, Inc. All rights reserved. Page 260 of 785 Working with Applications Kony Studio User Guide - 2.1 f. Deeplink URL Scheme: specifies a url to which the application will deeplink to. If the application name is southwest then the url scheme that the other applications can use to launch the southwest application is southwest://. For more information about deeplinking refer,Deeplinking. l Platform Settings: Using the Platform Settings Area, you can set certain default properties for an application for iPhone. o Generic exception alert: When true, generic exception alerts like "system error" are fired and when false detailed exception message is shown as alert. Best practice is to be use true for release mode and false for debug mode. o Exception alert: When true, system throughs the exception alerts otherwise (with false) app would crash in case of exception instead of alert. Best practice is to be use true for release mode and true for debug mode. o Globals monitoring: If set to true, the information like number of variables of the given type used in the app. Possible types are Strings, tables, numbers, closures, forms, other objects is printed in the logs. o Paste Board Type: It will allow the user to copy paste content from the app to external writable area like message etc. system level - it will allow to copy paste into other applications. Applevelpersistent - it will allow to copy paste within the app and the messages are persistent will be available across the app restarts. Applevelnonpersistent - it will allow to copy paste within the app and the messages are Not persistent and will not be available across the app restarts. Nopasteboard - it will not allow paste anywhere. o Allow self signed certificate: By default it is false, if true, it allows self signed certificate for development. Note: Allow Bundled option will not work in Android 2.3.x OS versions due to certificate chaining issue (causes certificate exception). This is a known Android native issue. For additional information on this issue, click here. To make the Bundled option work in Android 2.3.x devices, root CA need to be omitted from the server end (as mentioned in the previous link). o Input Accessory View Type: The input accessory view type for widgets like text box, calendar, grouped widgets etc where you have next previous cancel buttons. This can be overridden by form level Input Accessory View Type. Copyright © 2012 Kony, Inc. All rights reserved. Page 261 of 785 Kony Studio User Guide - 2.1 Working with Applications o Anti Aliased Drawing: If set to true, allows smoother widgets and layout without any jagged edges. o Camera Settings: Allows to set images to the icons which appear on the camera such as cancel icon, settings icon, tapanywhere. o Backward_compatibility_mode: By default it is false, if true it will allow the application feature to behave as it would have behaved on earlier version (if there is any behavioral change in the latest version) 6. Under the BlackBerry tab, set the following properties: You can deeplink an application from a message or an email on your device/emulator. Suppose you have a sample application called App1 uploaded on your device, to launch that application using an email or a message use the following: a. Service Identifier Pattern: Specifies a regular expression using which the application will be launched through a message or an e-mail. Suppose you specify the Service Identifier Patten as mytargetapp for App1 and build the application, whenever you compose a message or an e-mail and type out mytargetapp, a link appears below the typed out text( i.e mytargetapp ) and a popup appears which shows the application to be launched. b. Service Menu Item Label: Specifies a label for the application to be launched. Suppose you set the label for an App as applicationtest, when the service identifier pattern is recognized and a popup appears showing the application to be launched, the application appears with the label applicationtest. 7. Under the BlackBerry 10 tab, set the following properties: a. Package Name: A universally unique application identifier. Must be unique across all BlackBerry Tablet OS applications. Using a reverse DNS-style name as the id is recommended. (for example, com.example.SampleApp.) b. Package Version: A string value of the format <0-999>.<0-999>.<0-999> that represents application version which can be used to check for application upgrade. Note: Consider the following while assigning the Package Version number: l Invalid value: 0.0.0 or 012.123.123; Do not prefix "0" to any integer. l Valid values: 0.0.1 to 999.999.999. Here "0" is not prefixed to any integer. c. Package Build ID: Fourth digit segment of the package version. First three segments are taken from the <versionNumber> element. Note: The Build ID element specifies the build identifier, which is an integer value between 0 to 32767. d. Author: The company or developer name. For example, Kony. e. Author ID: The value provided to you by the BlackBerry Signing Authority server. You can get this ID from the BlackBerry IDE. To get your Author ID, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 262 of 785 Working with Applications Kony Studio User Guide - 2.1 a. Create an new BlackBerry project or use any existing project. b. Double-click the bar-descriptor.xml file. c. In the editor, under Author Information section, click Set from Debug Token. f. Orientation l l l l Default: Uses the device type to orient your application to the default orientation for your device type. The default is TOP_UP orientation, meaning the typical position of the device when used. For a smartphone that means portrait and for a tablet that means landscape. Auto-orient: Uses the physical position of the device to orient your application. The screen changes the orientation of the displayed application to match the physical positioning of the device. For example, if you are holding the device in portrait orientation, and turn the device 90 degrees to be in landscape orientation, then the display will reorient to show the application in landscape mode. Landscape: Locks the orientation of your application to landscape. Regardless of the physical position of the device, the application is only displayed in landscape mode. Portrait: Locks the orientation of your application to portrait. Regardless of the physical position of the device, the application is only displayed in portrait mode. For more information, see BlackBerry documentation. g. Description: Displayed in the BlackBerry Tablet OS application installer. h. Application Theme l Default: Retain the theme as defined in the device. For example, in Z10 it is Bright and in Q10 it is Dark. l Bright: Set to override the device theme to Bright. l Dark: Set to override the device theme to Dark. i. Keystore Password: Refers to the password used to open the container where the certificate will be stored. Note: This password must match the password that you provided while configuring the Signing Keys. j. Permissions: Double-click on each entry to select the permission. It is mandatory to select all the required permissions to use the phone functionality. The following are the permissions provided: l l l access_sms_mms Allows the app to access the text messages stored on the device. This access includes viewing, creating, sending, and deleting text messages. access_location_services Allows the app to access the current GPS location of the device. access_internet Allows the app to use an Internet connection from a Wi-Fi, wired, or other connection. Copyright © 2012 Kony, Inc. All rights reserved. Page 263 of 785 Working with Applications Kony Studio User Guide - 2.1 This permission is required to access a destination that is not local on the user's device. This permission is provided by default. l l l l l l l l access_pimdomain_calendars Allows the app to access the calendar on the device. This permission includes viewing, adding, and deleting calendar appointments. access_shared Allows the app to read and write the files that are shared between all apps on the device. This permission allows the app to access pictures, music, documents, and other files that are stored on the user's device, at a remote storage provider, on a media card, or in the cloud. read_device_identifying_information Allows the app to access unique device identifiers such as the PIN and serial number. This permission also allows you to access SIM card information on the device. access_phone Allows the app to determine when a user is on a phone call. This access also allows an app to access the phone number assigned to the device and send DTMF (Dual Tone Multi-Frequency) tones. use_camera Allows the app to access any of the data coming from cameras on the device. This permission allows an app to take pictures, record video, and use the flash on the device. access_pimdomain_contacts Allows the app to access to the contacts stored on the device. This permission includes viewing, creating, and deleting contacts on the device and SIM card. access_pimdomain_messages Allows the app to access the email and PIN messages stored on the device. This access includes viewing, creating, sending, and deleting messages. _sys_use_consumer_push Allows the app to use the BlackBerry Push Service with the BlackBerry Internet Service. This permission allows an app to receive and request push messages. To use the Push Service with the BlackBerry Internet Service, you must register with BlackBerry. When you register, you receive a confirmation email message that contains information that the application needs to receive and request push messages. For more information, see BlackBerry documentation. 8. Under the Windows Phone 7 and above tab, set the following properties: a. You can set Windows Views using the Common subtab. For more information on using Windows Views, refer Views. b. Under the Phone 7 subtab: l Click Generate to generate a GuId for the Windows Mobile. This GuId enables you to view the application on Windows 7 emulator. You need to perform this step only once after you install the Windows 7 SDK. Copyright © 2012 Kony, Inc. All rights reserved. Page 264 of 785 Working with Applications Kony Studio User Guide - 2.1 Note: Note: You must have the Windows 7 SDK installed to generate the Windows Mobile GuID. For more information about installing Windows 7 SDK, see Kony Studio Installation Guide. l Browse and select a Tile Image for Windows platform. This image must be of the size 173x173 pixels and is used as the image for the tile (application icon). c. Under the Mango (7.5) subtab: l l l l l Tile Title - Specifies the Title Headers for the application which is displayed as a tile. Chose 3D Models Folder - Specifies the folder where the fbx files are stored. The Run button next to this field, converts the .fbx file into a format that can be used by Windows. Ringtone - You can add ringtones for your device using this field. To add a ringtone Manifest Properties - set the appropriate permissions to true using the manifest properties area. For more information refer, Windows Manifest. App Title - You can add an Application title to be displayed under the application tile for various locales. d. Under the Windows Phone 8 subtab: l l l Display name: The display name of the application visible in the applications list. Description: Specifies the description to be displayed on the tile. For example a tile on finance can contain a generic description about stocks. Supported Resolutions Label: Specifies the supported resolutions to define the look and feel of your app in the Store. For more information about each of the supported resolutions and versions refer Supported Resolution. Setting Capabilities Using the capabilities tab you can: Enable or disable permissions for the Windows phone 8 application using this pane. For more information about each of the permissions refer Capabilities and requirements. i. To enable permissions, select the permissions that are currently false and click Add >. ii. To disable permissions, select the permissions that are currently true and click < Remove. Setting Packaging Using the Packaging tab, you can set the : Author: The app author's name. Publisher: The publisher of the app. This default value is the name of the project. This attribute is required for certain types of apps, such as push-enabled apps. Copyright © 2012 Kony, Inc. All rights reserved. Page 265 of 785 Working with Applications Kony Studio User Guide - 2.1 Version: Version of the project. Publisher ID: KonyLabs is the default Publisher ID of the project. Setting Requirements Using the Requirements tab you can: Enable or disable permissions for the Windows phone 8 application using this pane. For more information about each of the permissions refer Capabilities and requirements i. To enable permissions, select the permissions that are currently false and click Add >. ii. To disable permissions, select the permissions that are currently true and click < Remove. 9. The Windows 8 properties are listed at Windows 8 native properties. 10. Click Finish. 7.25.11 Application Settings This feature allows the developer to enable application level settings so that the end users of an application can modify configurations and change the application behavior. For instance developers can choose to set the following for an application: l define views for widgets. l change dynamic properties for widgets. l enable and disable components of the application, such as videos. To set App Settings properties, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 266 of 785 Working with Applications Kony Studio User Guide - 2.1 1. Go to Project Properties window. 2. Click the App Settings tab. The following dialog appears. 3. The settings under the common header are common across all platforms. You can create platform specific settings under a new header by clicking the Configure button and setting platforms on which the setting will be rendered on. 4. Select to add a setting for an application that the user can configure. 5. Set the following: l Key: specifies a unique identifier for each setting. l Display Name: specifies the name to be displayed for a setting(key). l Display Option: specifies the way in which the settings are set. For example, if you set your display option as a textbox in the settings of the application, once the application is built and deployed , you can set the settings for that key as text in a textbox. Copyright © 2012 Kony, Inc. All rights reserved. Page 267 of 785 Working with Applications l l Kony Studio User Guide - 2.1 Keyboard Type: specifies a keyboard type if the Display Option set is textbox. For more information on Keyboard types refer the Kony Widget User's Guide. Default Value: Specifies the default value for each key. The figure below depicts the settings built and deployed on iPhone that corresponds to the Application settings configured in IDE. Use cases for different Display Options Textbox You can set a display option as a textbox and use the application settings APIs to read or write the values set to the application. In the figure above User Name is a value entered in a textbox. You can read this key and its corresponding value use it anywhere in the application. The values in this field are stored as a string in appsettings. Label You can set a label in application settings for two purposes. First to read/write the value of the label to the application. Second you can use the label as a separator in the settings area itself to show different types of settings. The values in this field are stored as a string in appsettings. Switch You can set permissions for an application using the Switch display option. For example if you use the appsettings APIs to read the value of the switch and if the value is false you can disable some functionality of that application. The values in this field are boolean. Copyright © 2012 Kony, Inc. All rights reserved. Page 268 of 785 Working with Applications Kony Studio User Guide - 2.1 Single Select If you set the Single Select display option, you provide the user with the option to select only one value from a list of given options. When you select your Display Option as singleselect, in the Default Value column click to define multiple values and the default value set is the first value in the first row. Suppose you define multiple views for a segment in the appsettings area, the user can select any one of the listed views using the settings. Using the appsetting APIs, the value the user selects can be assigned to frm.segment.view="" and the view can be changed at runtime. The values in this field are stored as string. The figure below depicts how single select is viewed on application settings. Multi Select If you set the Multi select display option, you provide the user to select multiple values from a list of given options. When you select your Display Option as multiselect, in the Default Value column click to define multiple values and the default value set is the first value in the first row. Suppose the user sets multiple values for locations, the locations set are returned as a lua table and can be assigned to any widget using the application settings APIs. The figure below depicts how multiselect is rendered on iPhone. Copyright © 2012 Kony, Inc. All rights reserved. Page 269 of 785 Working with Applications Kony Studio User Guide - 2.1 7.26 Using Code Assistance Code Assistance (Intellisense) prompts the developers with possible completions while writing the code. The relevant hints appear on the screen depending on the code entered. Code Assist feature allows the application entities like methods, namespaces, variables, skins, functions, widgets, and properties to be listed for insertion into the Script Editor. This feature is similar to the Code Assist feature provided by the Eclipse. Important: The Code Assist feature is available within a code module. Within the Event Editor, the code assist feature is available for snippets, decisions, alerts, conditions, a simple local variable or a collection variable. 7.26.1 Prerequisites From 5.0 onwards to enable code assist ensure that you delete tk.eclipse.plugin.htmleditor_2.1.0.jar and org.eclipse.wst.jsdt.* from your dropins or plugins folder. The Code Assist feature for JavaScript application is inbuilt and you do not have to download any plugin for it. To enable Code Assist in Kony Studio for Lua, make sure that you: l Delete all the existing org.kepler plug-ins and features from the Eclipse folder. l Download the following plug-ins into the dropins folder of Eclipse: o org.keplerproject.ldt.core o org.keplerproject.ldt.debug.core o org.keplerproject.ldt.debug.ui o org.keplerproject.ldt.launcher o org.keplerproject.ldt.ui.baseExts o org.keplerproject.ldt.ui o org.keplerproject.ldt.win32 o org.keplerproject.luadoc o org.keplerproject.lualogging. After you perform the above steps, run Eclipse from the command line using the following command: eclipse.exe -clean Copyright © 2012 Kony, Inc. All rights reserved. Page 270 of 785 Working with Applications Kony Studio User Guide - 2.1 7.26.2 Advantages The advantages of Code Assist are as follows: l Enables the developers to write code in an efficient and accurate manner. l Avoids typographical errors while writing code. l Reduces the development time. l Helpful to the developers with minimal knowledge about Kony Platform. l No dependency on other sources for documentation. 7.26.3 Capabilities Code Assist supports the following elements/components of an application: l l Kony APIs - all the non-UI APIs supported by Kony. Common properties (properties applicable across all the platforms) of a widget that are accessible through code. l Platform specific properties accessible from code. l Forms, popups (within the application), and the corresponding widgets on a form/popup. l Skins - all the skins defined within an application. l User-written functions (collection of functions from all the Lua files). l Global variables l o defined through the IDE o declared in all the Lua files. Lua keywords (like function, if, else, end, do, while, local, ifdef, and so on). Note: All the content in the Code Assist window is sorted alphabetically. 7.26.4 Outline View The Outline View displays a list of all the user-defined functions within a Lua file (that is open and is in focus in the Script Editor). Copyright © 2012 Kony, Inc. All rights reserved. Page 271 of 785 Kony Studio User Guide - 2.1 Working with Applications l By default, the user-defined functions are listed in the order in which they are defined in the Lua file. Click to sort the user-defined functions alphabetically. This is toggle icon. Click this icon again to sort the user-defined functions in the default order. l Double-click a user-defined function in the Outline View to navigate to that function block in the Lua file. 7.26.5 Using Intellisense for Lua and JavaScript You can invoke Code Assist window with a key combination of Ctrl and Space (hold the Ctrl key and press the Spacebar on the keyboard) in the Script Editor. To access the code assist for JavaScript modules, use the Kony JavaScript Editor denoted by . Important: If you want to use the code assist in the Kony JavaScript Editor ensure that you delete the tk.eclipse.plugin.htmleditor_x.x.x plugin from your dropins folder. l If you press Ctrl + Space on a new line within the Script Editor, Snippets, Decisions, Conditions, Alerts, Simple local Variables, or Collection Variables the following will appear: o All forms and popups defined in the application. o All headers and footers defined in the application. o All the skins defined in the application. o All the Kony APIs. o All the user-written functions. o All Lua keywords. Copyright © 2012 Kony, Inc. All rights reserved. Page 272 of 785 Kony Studio User Guide - 2.1 Working with Applications o All global variables. Note: If you type a few characters and press Ctrl + Space , all the objects that begin with those characters appear in the Code Assist window. For example, if you type frm and press Ctrl + Space , all the forms whose names start with frm appear in the Code Assist window. l If you type the name of an object and a period (dot) to invoke a method or property, Code Assist pops up a small window that displays the available methods and properties for that object. For example, if you want to access the properties or methods of the Form widget, type form followed by a period (dot) to invoke the Code Assist window as shown below: The following table provides a description of each icon in the Code Assist window: Icon No icon Description Lua keyword Method or User-written function Kony API Skin within the application Form within the application Popup within the application Global Variable (simple) Global Variable (collection) Property that is only readable Property that is only writeable Property that is both readable and writeable Skin property that is only writeable Copyright © 2012 Kony, Inc. All rights reserved. Page 273 of 785 Working with Applications Kony Studio User Guide - 2.1 To use the Code Assist, follow these steps: 1. When the Code Assist window pops up: o To access with the mouse - Double-click the property/method/API that you want to use with the object that you just typed. o To access with the keyboard - Use Up and Down arrows to select the appropriate property/method/API and press Enter key. 2. Replace the signature with the actual parameters in case of APIs and methods. Note: Use Ctrl + <mouse left click> on a user-defined Lua function to open the corresponding Lua file with the function definition selected. 3. Select a form/popup name in the Code Assist window to access the widgets/properties associated with the selected form/popup. Copyright © 2012 Kony, Inc. All rights reserved. Page 274 of 785 Working with Applications Kony Studio User Guide - 2.1 4. To access the documentation associated with a specific property/method/API, do any of the following: o Hover over the completed code statement. o Focus on a specific method/API/property in the Code Assist window. 5. Click the documentation window to resize it. 6. Right-click on any of the windows where code assist is supported, and select any one of the following options: l Cut l Copy l Paste l Select All l Undo l Redo 7.27 Importing Existing Applications If you have applications that were created earlier at some other location, you do not have to re-create your applications. You can import the existing applications into the current workspace from the IDE and work on them. Every application that is available in the current workspace or that has been imported into the current workspace is visible under the Applications view and Navigator view. If you have imported an application into the workspace, it may not be automatically visible. You must right-click and select Refresh All in the Applications view area or select Refresh in the Navigator view area to update the view with the list of applications. Note: If the application is not available under the Applications view or Navigator view, you cannot work on it. Copyright © 2012 Kony, Inc. All rights reserved. Page 275 of 785 Working with Applications Kony Studio User Guide - 2.1 To import existing applications, follow these steps: 1. Launch Eclipse. 2. Select File -> Import or right-click in the Navigator view area and select Import.The Import window appears. 3. Under General, select Existing Projects into Workspace. 4. Click Next. 5. Select Select root directory and click Browse. Root directory is the folder that contains the applications. 6. Select the required directory and click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 276 of 785 Working with Applications Kony Studio User Guide - 2.1 7. Eclipse searches for all the applications available within the selected root directory as shown below. 8. Select the applications you want to import under the Projects frame. 9. Select Copy projects into workspace if you want to copy the application into the workspace. Note: If you do not select this option, the application is retained at its original location and all the changes you make are reflected in the application residing at the original location. 10. Click Finish. Eclipse imports the selected application into the workspace. 11. Select Refresh All in the context menu to view the imported application in the Applications view. 7.28 Exporting Existing Applications You can choose to export an application when you want to: l share the application with someone l take a backup of the application l integrate the application with a Version Control System or Content Management System. Copyright © 2012 Kony, Inc. All rights reserved. Page 277 of 785 Working with Applications Kony Studio User Guide - 2.1 To export existing applications, follow these steps: 1. Launch Eclipse. 2. Open the application you want to export. 3. Select File -> Export. The Export window appears. 4. Under General, Select File System. 5. Click Next. 6. Select the application you want to export from the left frame of the screen. 7. Select the folder to which you want to export the application. The folder you select is the destination folder. Copyright © 2012 Kony, Inc. All rights reserved. Page 278 of 785 Working with Applications Kony Studio User Guide - 2.1 8. Select the appropriate options. Create only selected directories is the default selection. Select this option when you want only the selected directories to be copied to the destination folder. 9. Click Finish. The application is successfully exported to the selected folder. 7.29 AndroidManifest File Every application developed in Kony Studio for Android platform has an AndroidManifest.xml file associated with the application. The manifest file has all the details that the Android platform needs to execute the application. It also provides information about the application components like: services, activities, and so on. This file is generated when you build the application on Android platform. Kony Studio enables and disables a few permissions in the AndroidManifest.xml file by default. When you build the application, the AndroidManifest.xml file is generated with the default permissions or with the permissions that you have set. The generated AndroidManifest.xml file is available at the following location: <Drive>/<Workspace>/temp/<AppName>/build/ luaandroid/dist/<AppName>. Kony Studio allows you to define the following options for AndroidManifest.xml file: l the supported screen sizes. l the supported SDK versions: minimum, target, and maximum. l ability to send Push Notifications. l various permissions for the application. For more information about AndroidManifest.xml file, see http://developer.android.com/guide/topics/manifest/manifest-intro.html. Copyright © 2012 Kony, Inc. All rights reserved. Page 279 of 785 Working with Applications Kony Studio User Guide - 2.1 Kony Studio enables and disables a few permissions in the AndroidManifest.xml file by default. When you build the application, the AndroidManifest.xml file is generated with the default permissions or with the permissions that you have set. The generated AndroidManifest.xml file is available at the following location: <Drive>/<Workspace>/temp/<AppName>/build/ luaandroid/dist/<AppName>. The following permissions are set to true by default: l ACCESS_NETWORK_STATE l INTERNET l READ_PHONE_STATE. The following is a basic AndroidManifest.xml file generated with the default permissions: <?xml version="1.0" encoding="utf-8"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.konylabs.testcal" android:versionName="1.0.0" android:versionCode="1"> <application android:label="@string/app_name" android:icon="@drawable/icon"> <activity android:name=".testcal" android:label="@string/app_name" android:launchMode="singleTask" android:configChanges="locale|keyboardHidden|orientation" android:screenOrientation="sensor" android:windowSoftInputMode="adjustResize"> <intent-filter> <action android:name="android.intent.action.MAIN" /> <category android:name="android.intent.category.LAUNCHER" /> </intent-filter> </activity> <uses-library android:name="com.google.android.maps"></useslibrary> <activity android:launchMode="singleInstance" android:name="com.konylabs.android.KonyMapsActivity"></activity> </application> <supports-screens android:anyDensity="true" android:smallScreens="true" android:normalScreens ="true" android:largeScreens="true"/> Copyright © 2012 Kony, Inc. All rights reserved. Page 280 of 785 Kony Studio User Guide - 2.1 Working with Applications <uses-sdk android:targetSdkVersion="4" android:minSdkVersion ="3"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_ STATE"/> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.READ_PHONE_ STATE"></uses-permission> </manifest> The following permissions are set to false by default: ACCESS_ COARSE_ LOCATION ACCESS_WIFI_ STATE BIND_DEVICE_ ADMIN BLUETOOTH_ ADMIN CALL_PHONE CHANGE_ NETWORK_ STATE CONTROL_ LOCATION_ UPDATES DISABLE_ KEYGUARD ACCESS_ ACCESS_FINE_ LOCATION_ LOCATION EXTRA_ COMMANDS ACCOUNT_ AUTHENTICATE_ MANAGER ACCOUNTS BIND_INPUT_ BIND_ METHOD REMOTEVIEWS BROADCAST_ BRICK PACKAGE_ REMOVED ACCESS_ MOCK_ LOCATION BATTERY_ STATS BIND_ WALLPAPER ACCESS_SURFACE_ FLINGER BIND_APPWIDGET BLUETOOTH BROADCAST_ STICKY BROADCAST_WAP_ PUSH CHANGE_ COMPONENT_ ENABLED_ STATE CHANGE_ CONFIGURATION CHANGE_WIFI_ CHANGE_WIFI_ MULTICAST_ STATE STATE CLEAR_APP_ CACHE CLEAR_APP_USER_ DATA DELETE_ CACHE_FILES DELETE_ PACKAGES DEVICE_ POWER DIAGNOSTIC EXPAND_ STATUS_BAR GET_PACKAGE_ SIZE INSTALL_ LOCATION_ PROVIDER FACTORY_ TEST FLASHLIGHT GET_TASKS GLOBAL_SEARCH INSTALL_ PACKAGES INTERNAL_ SYSTEM_WINDOW MANAGE_APP_ TOKENS MASTER_ CLEAR MODIFY_AUDIO_ SETTINGS MOUNT_ UNMOUNT_ FILESYSTEMS NFC PERSISTENT_ ACTIVITY CALL_ PRIVILEGED DUMP FORCE_BACK GET_ ACCOUNTS HARDWARE_ TEST INJECT_ EVENTS KILL_ BACKGROUND_ PROCESSES MANAGE_ ACCOUNTS MOUNT_ MODIFY_PHONE_ FORMAT_ STATE FILESYSTEMS CAMERA Copyright © 2012 Kony, Inc. All rights reserved. Page 281 of 785 Kony Studio User Guide - 2.1 Working with Applications PROCESS_ OUTGOING_ CALLS READ_INPUT_ STATE REBOOT RECORD_AUDIO SET_ALARM SET_ PREFERRED_ APPLICATIONS SET_ WALLPAPER_ HINTS SYSTEM_ALERT_ WINDOW WAKE_LOCK WRITE_ GSERVICES READ_ CALENDAR READ_CONTACTS READ_FRAME_ READ_HISTORY_ BUFFER BOOKMARKS READ_LOGS READ_SMS READ_SYNC_ SETTINGS READ_SYNC_STATS RECEIVE_MMS RECEIVE_SMS RECEIVE_WAP_ PUSH RECEIVE_ BOOT_ COMPLETED REORDER_ TASKS SET_ALWAYS_ FINISH RESTART_ SEND_SMS PACKAGES SET_ANIMATION_ SET_DEBUG_ SCALE APP SET_PROCESS_ SET_TIME LIMIT SIGNAL_ PERSISTENT_ PROCESSES UPDATE_ DEVICE_STATS WRITE_APN_ SETTINGS WRITE_ HISTORY_ BOOKMARKS STATUS_BAR USE_ CREDENTIALS WRITE_ CALENDAR SET_ACTIVITY_ WATCHER SET_ORIENTATION SET_TIME_ ZONE SET_WALLPAPER SUBSCRIBED_ FEEDS_READ SUBSCRIBED_ FEEDS_WRITE USE_SIP VIBRATE WRITE_ CONTACTS WRITE_EXTERNAL_ STORAGE WRITE_SECURE_ WRITE_ SETTINGS SETTINGS WRITE_SMS WRITE_SYNC_ SETTINGS 7.29.1 Enable/Disable Permissions You can change the permissions for the AndroidManifest.xml file based on the requirements of the application. To set the permissions for the AndroidManifest file, follow these steps: 1. Go to Applications View. 2. Right-click the required application and select Properties. 3. Go to Native App tab. Copyright © 2012 Kony, Inc. All rights reserved. Page 282 of 785 Working with Applications Kony Studio User Guide - 2.1 4. In the Native App tab, go to Android tab. 5. Select the required options under Supported Screens. l l Resizable - This property indicates whether the application is resizable for different screen sizes. This property is deprecated by the Android SDK and is supported only for customer on the 2.6 plugin. This property enables you to run an application in the compatibility mode. For more information, refer http://developer.android.com/guide/topics/manifest/supports-screenselement.html Select Support Margins and Pixels in DPI if required. Margins and Paddings specified in the application (for Android) for each widget are converted based on the density of the device. According to android SDK, the base density per inch (DPI) is 160 pixels, which is considered as a reference while converting. For example, if you specify a padding of 1 pixel in the IDE, it is treated as exactly 1 pixel on a device which has 160 DPI and the same is converted to 1.5 times in a device with 240 DPI device and 0.75 times in a device with 120 DPI. The resulting pixels are rounded. 6. Under SDK Versions: i. Select the Minimum SDK Version that needs to be supported for the application. Default value is 1.6. This default value is applicable only for the applications created using Kony Studio. Copyright © 2012 Kony, Inc. All rights reserved. Page 283 of 785 Working with Applications Kony Studio User Guide - 2.1 ii. Select the Target SDK Version that needs to be supported for the application. Note: The Target SDK Version must be greater than or equal to the Minimum SDK Version. iii. Select the Maximum SDK Version that needs to be supported for the application. 7. Select C2DM if you want to enable Push Notifications for the application. This option copies the libraries required for push notification into the project during build time. Important: C2DM (Android Cloud to Device Messaging Framework) is supported only for Android SDK Versions 2.2 and above. 8. Enter a value for Package Name. This is the name with which the application is submitted to Android Market. Android Market is an online software store developed by Google for Android mobile devices. A software program called Market is pre-installed on most of Android mobile devices. This software allows the users to browse and download third-party applications. This name is used to search the application in Android Market. Note: The name you specify for Android Package must contain at least two segments. A segment is a valid Java package name. The following are a few examples of valid Android Package names: o com.konylabs.<ApplicationName> o com.kony.<ApplicationName> o com.konysolutions.<ApplicationName> o com.kony.<ApplicationName>_Android. 9. Under Install Location, select the Use Location Preference checkbox and then select Auto or Prefer SD Card. This property governs the location where the application is deployed. l l Auto - indicates that the application is deployed on the device and can be moved to SD Card later if required. Prefer SD Card - implies that the application is deployed on the storage card and cannot be moved to the device memory at a later point of time. Note: This will only work if the min-target sdk is 2.2. 10. Splash Screen Orientation Mode - specifies the supported orientations for the Splash screen on Android on the application level. Additionally add an image by navigating to resources > mobilerichclient> android. Right-click Android and select Add Resource Folders. Set the desired Screen Orientation and click OK. Add required images under the newly created folder. 11. In the Manifest Properties pane under the Map Permissions tab, set the permissions to true or false based on the application requirements. Copyright © 2012 Kony, Inc. All rights reserved. Page 284 of 785 Working with Applications Kony Studio User Guide - 2.1 i. To enable permissions, select the permissions that are currently false and click Add >. ii. To disable permissions, select the permissions that are currently true and click < Remove. iii. Tags: You can add tags to the Android manifest file directly from Kony Studio using Child tag entries under<manifest> tag area and Child tag entries under <application> tag area. For more information on the tags you can add with the manifest or application tags refer http://developer.android.com/guide/topics/manifest/manifest-intro.html. iv. Deeplink URL Scheme: You can use the URL Scheme tab for Deeplinking. The values for Scheme/ port/ path/host/pathprefix/path pattern specified under this tab can be used to deeplink to a particular URL directly. For instance, if you set the masterdata for a browser widget to be a URL to deeplink, use the following format, scheme://host:port/pathorpathPrefixorpathPattern. For more information on each of the values available under the URL Scheme tab, refer http://developer.android.com/guide/topics/manifest/data-element.html#path Important: For URL scheme in Android, please note that the scheme name should be in lower caps otherwise it will not work in higher versions (Android 4.0 and above) or Android devices. 12. Click Finish. When the application is built on Android platform, the manifest file is generated with the options selected/specified in the above step. 7.30 Windows Manifest File Every application developed in Kony Studio for Windows platform has an WMAppManifest.xml file associated with the application. The manifest file has all the details that the Windows platform needs to execute the application. It also provides information about the application components like, permissions, application titles, and so on. This file is generated when you build the application on Mango platform. Kony Studio allows you to define the following options for WMAppManifest.xml file: l ability to send Push Notifications. l various permissions for the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 285 of 785 Working with Applications l Kony Studio User Guide - 2.1 enabling search extensibility For more information about WMAppManifest.xml file, see http://msdn.microsoft.com/en-us/library/ff769509%28v=vs.92%29.aspx Kony Studio enables and disables a few permissions in the WMAppManifest.xml file by default. When you build the application, the WMAppManifest.xml file is generated with the default permissions or with the permissions that you have set. The generated WMAppManifest.xml file is available at the following location: <Drive>/<Workspace>/temp/<AppName>/build/ luaandroid/dist/<AppName>. The following permissions are set to false by default: l ID_CAP_CAMERA l ID_HW_FRONTCAMERA The following is a basic WMAppManifest.xml file generated with the default permissions: <?xml version="1.0" encoding="utf-8" ?> - <Deployment xmlns="http://schemas.microsoft.com/windowsphone/2009/deployment" AppPlatformVersion="7.1"> - <App xmlns="" ProductID="{006c6c28-9c66-492e-bc91-958861c4b501}" Title="testintevents1" RuntimeType="Silverlight" Version="1.0.0.0" Genre="apps.normal" Author="Framework author" Description="Sample description" Publisher="Framework"> <IconPath IsRelative="true" IsResource="false">ApplicationIcon.png</IconPath> - <Capabilities> <Capability Name="ID_CAP_ISV_CAMERA" /> <Capability Name="ID_CAP_MICROPHONE" /> <Capability Name="ID_CAP_CONTACTS" /> <Capability Name="ID_CAP_NETWORKING" /> <Capability Name="ID_CAP_PUSH_NOTIFICATION" /> <Capability Name="ID_CAP_GAMERSERVICES" /> <Capability Name="ID_CAP_IDENTITY_DEVICE" /> <Capability Name="ID_CAP_LOCATION" /> <Capability Name="ID_CAP_WEBBROWSERCOMPONENT" /> <Capability Name="ID_CAP_APPOINTMENTS" /> <Capability Name="ID_CAP_SENSORS" /> <Capability Name="ID_CAP_PHONEDIALER" /> <Capability Name="ID_CAP_MEDIALIB" /> Copyright © 2012 Kony, Inc. All rights reserved. Page 286 of 785 Working with Applications Kony Studio User Guide - 2.1 <Capability Name="ID_CAP_IDENTITY_USER" /> </Capabilities> - <Tasks> <DefaultTask Name="_default" NavigationPage="MainPage.xaml" /> </Tasks> - <Tokens> - <PrimaryToken TokenID="FrameworkToken" TaskName="_default"> - <TemplateType5> <BackgroundImageURI IsRelative="true" IsResource="false">Images/Background.png</BackgroundImageURI> <Count>0</Count> <Title>abcd</Title> </TemplateType5> </PrimaryToken> </Tokens> - <Extensions> <Extension ExtensionName="Bing_Products_Arts_and_Crafts" ConsumerID="{5B04B775-356B-4AA0-AAF8-6491FFEA5661}" TaskID="_ default" ExtraFile="Extensions\\Extras.xml" /> </Extensions> </App> </Deployment> 7.30.1 Enable/Disable Permissions You can change the permissions for the WMAppManifest.xml file based on the requirements of the application. To set the permissions for the WMAppManifest.xml file, follow these steps: 1. Go to Applications View. 2. Right-click the required application and select Properties. 3. Go to Native App tab. Copyright © 2012 Kony, Inc. All rights reserved. Page 287 of 785 Working with Applications Kony Studio User Guide - 2.1 4. In the Native App tab, go to Windows Phone 7 and above tab. Select Mango 7.5. 5. In the Manifest Properties pane, set the permissions to true or false based on the application requirements. i. To enable permissions, select the permissions that are currently false and click Add >. ii. To disable permissions, select the permissions that are currently true and click < Remove. Copyright © 2012 Kony, Inc. All rights reserved. Page 288 of 785 Working with Applications Kony Studio User Guide - 2.1 6. Click Finish. When the application is built on Windows platform, the manifest file is generated with the options selected/specified in the above step. 7.30.2 Setting Cards to enable Search extensibility Using search extensibility, users who search the web for products can launch a relevant page in the application from Bing search results. For example if you have an XYZ shopping application on your phone, and you have searched for product 1 on bing, you can launch the relevant page in the XYZ application which shows the results for Product 1. For more information on Search extensibility refer http://msdn.microsoft.com/enus/library/hh202957%28v=vs.92%29.aspx To enable search extensibility, use the Cards Tab in the Manifest Properties Area. You can set Card types and Card names for the application you are creating. When you search for a product on Bing, it associates each search term with a card type. For example, if you are searching for a certain toy on bing , the XYZ application will appear in the corresponding applications pivot page (the XYZ application must be installed on your device or emulator and must be registered with a Product Card which you set in the Manifest Area). If you tap on the application, it will launch and display the corresponding extension, Bing_Products_toys. You can set internationalization keys for the card types you register. Copyright © 2012 Kony, Inc. All rights reserved. Page 289 of 785 Changing the Development Language of a Project Kony Studio User Guide - 2.1 8. Changing the Development Language of a Project With the 5.0 release Kony platform now allows the developer to use either JavaScript or Lua for developing applications. The developer is typically asked to choose the development language when creating a new application. One can also change the language midway through the application development process. 8.1 Converting a Lua project to JavaScript: To convert an existing (4.1.x) or a new Lua project to a JavaScript application: 1. Upgrade your project by right clicking the application and selecting Utilities > Upgrade Actions. 2. Right click the application and select Change Development Language to JavaScript. A confirmation dialog appears. 3. Click Yes to run the Lua2JS tool. 4. A message appears stating that the project type has been changed. You can view the status of the conversion in the Console. 8.2 Converting a JavaScript project to Lua: To convert a JavaScript project to Lua : 1. Right click the application and select Change Development Language to Lua. A confirmation dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 290 of 785 Changing the Development Language of a Project Kony Studio User Guide - 2.1 2. Click Yes to convert the project. 3. A message appears stating that the project type has been changed. You can view the status of the conversion in the Console. 8.3 Important Considerations when converting a Lua Project to JavaScript: When you change the project type from Lua to JavaScript note that: Even though Lua2JS tool works for most of the Lua code patterns / features below are some of the areas it does not address: 1. Avoid Multiple return types: Multiple return types from functions are not supported in JavaScript. Hence any function that returns multiple return types has to be changed to return a Lua table with multiple keys. Incorrect Lua code function xyz() return a,b,c; end Correct Lua code function xyz() return {a,b,c}; -- return table containing multiple Copyright © 2012 Kony, Inc. All rights reserved. Page 291 of 785 Changing the Development Language of a Project Kony Studio User Guide - 2.1 values end 2. Avoid comments starting with "*" : Single line comments should not be started with a star "*". Resultant translation will provide "//*" which happens to be a start for a multiple line comment. Lua Example --********** Hello When converted to JavaScript //********** Hello 3. Avoid starting comments with "#" : JavaScript pre-processor uses the pattern //# to identify the preprocessor macros and results in an error when incase the macros not found. Lua Example --#Hello When converted to JavaScript //#Hello 4. FFI definitions defined in Lua project will not be carried over : The definitions have to be redefined in JavaScript. 5. Avoid variable names using JavaScript keywords : Variable and Function names using JavaScript reserved keywords will be reported as errors. For e.g. the below line of lua code will report an error, as 'null' is a reserved keyword in JavaScript. local null = "null object". 6. If "variables" have been used as keys when creating Lua tables , the converted JavaScript code will be erroneous. Incorrect Initialization: local i = "bar" local data = { [i] = "foo"} print(data.bar)-- prints foo When Converted to JavaScript: var i = "bar" var data = { i : "foo"} print(data.bar) //prints null Correct Initialization: Copyright © 2012 Kony, Inc. All rights reserved. Page 292 of 785 Changing the Development Language of a Project Kony Studio User Guide - 2.1 local i = "bar" local data = {} data[i] = "foo" print(data.bar) -- prints foo When Converted to JavaScript var i = "bar" var data = {} data[kony.decrement(i)] = "foo" print(data.bar)//prints foo 6. If SPA is one of the target deployment channels, the Lua code should follow the SPA development guidelines. 7. A project can have modules only in one language not both. 8. Avoid a LuaTable containing both list as well as hash : Mixed mode collections are not supported in JS. So Lua tables having both key, value pairs and values shall fail in JS. A Lua table must contain either a set of key,value pairs only or values only, but not both. function xyz() abc={123 ,["apple"] = green, ["mango"] = "orange"} --This is a mixed mode example where the object comprises both list values as well as key-value pairs. --This is not allowed in JS end 9. Any new APIs and widgets defined for 5.0 Lua will not be converted to JS in the 5.0 Kony Studio. 10. Always initialize Global Variables : Global variables must be declared/initialized beforehand.A undefined variable in lua is defined as "undefined" in JS. In Lua a undefined variable may exist with a value of "nil" but in JS it will assume a value of "undefined". A check for "nil" shall fail in this case. It is advised to initialize variables with "nil" in Lua. Lua example function xyz() if(foo == nil) print() end end When converted to JavaScript function xyz() { if(foo == null)//This check will fail since foo is undefined Copyright © 2012 Kony, Inc. All rights reserved. Page 293 of 785 Changing the Development Language of a Project Kony Studio User Guide - 2.1 { } } 11. Make appropriate index conversion : JavaScript uses a zero based index while Lua uses 1 based index when accessing values in a collection. Though the Lua2JS tool takes care of index conversion as much as possible one can still find hard coded indices that need to be manually changed. 12. M4 Macros declared in lua must follow the syntax : "ifdef(![xxxxxx]!, ![yyyyyy]!,![zzzzzzz]!)" 13. In a macro, the last code statement should not be a comment. "ifdef(![xxxxxxx]!,![--This is true]!)" or "ifdef(! [xxxxxxx]!,![x = 20 --This is true]!), results in failure of Lua2JS conversion 14. Comments will not be carried forward in case they are declared inside a macro. "ifdef(![xxxxxxx]!,![--[[This is true--]]]!)" shall result in ifdef (xxxxx) endif. 15. Using table.insert , table.get and table.remove for Tables that only have the "list" part will result in indexing errors. Instead use "[]" to access any indexed value of a Lua Table. 16. Avoid module names and Forms having same case insensitive names (for e.g. selectFlight.lua and SelectFlight.kl). The Lua compiler takes care of resolving names but incase of JavaScript since the source is retained as is at runtime, having files with same name will result into errors. 17. If a Lua Table is defined and never initialized with any values in Lua, there is a possibility that the Lua2JS tool and underlying platforms may misinterpret the intent of the Lua code. local x = {}--no value initialized --Lua2JStool may not be able to convert since the above could be an array or an hash 18. Avoid using property/key names starting with a number: In case a property/key name starts with a number, it cannot be accessed by "." dot operator instead we need to use "[]" square parenthesis. Original Lua Code: frmStocksSummary.label52WkHigh.text = GetStockSnapshot.52WeekHigh; Modified Lua Code for Lua2JS conversion: frmStocksSummary.label52WkHigh.text = GetStockSnapshot ["52WeekHigh"]; Copyright © 2012 Kony, Inc. All rights reserved. Page 294 of 785 Changing the Development Language of a Project Kony Studio User Guide - 2.1 8.4 Important Considerations when converting a JavaScript Project to Lua When you change the development language type from JavaScript to Lua note that: 1. One can change the development language at any stage of the project. 2. Unlike the Lua2JS tool, there is no JS2Lua tool. Thus all the modules and event handling code (in snippets) have to be manually rewritten in Lua. Copyright © 2012 Kony, Inc. All rights reserved. Page 295 of 785 Kony Studio User Guide - 2.1 Working with Windows Phone7 Sequences or Views 9. Working with Windows Phone7 Sequences or Views An application developed for Windows Phone supports sequences (Pivot Views and Panorama Views) to present information to the user. These views govern the way information is displayed to the user. l l Pivot View places individual views horizontally next to each other and manages left and right navigation. Panorama View uses a long horizontal canvas that extends beyond the screen width. Pivot View l l l Splits the screen and creates panels that can be viewed one at a time Scrolls horizontally Used to present information divided into several subsets Panorama View l l l Splits the screen into tabs Displays complete content of one tab and partial content of another tab Scrolls horizontally Kony Studio provides you an option to define the forms that need to be included in the Pivot Views or Panorama Views. Based on the content in the forms, you can decide to include the forms either in Pivot View or Panorama View. 9.1 Defining a Pivot Sequence To define a pivot view, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Properties. The Application Properties dialog appears. 3. Under the Native Application Tab, click the Windows Phone 7 and above subtab. 4. Right-click Pivot Views and select Add Pivot View or select Pivot View and click the Add ( button. 5. Under the common subtab, select Pivot View and click the Add ( ) ) button. Copyright © 2012 Kony, Inc. All rights reserved. Page 296 of 785 Working with Windows Phone7 Sequences or Views Kony Studio User Guide - 2.1 6. A pivot view is created with a unique ID. i. In the properties area, select the General tab and execute the following steps: a. The ID is automatically created. Modify the ID if required. Note: The ID of each pivot view in an application must be unique. b. Enter a Title for the Pivot View. c. Select the i18n Key for the Title, if required. d. Select a Skin for the Pivot View. If you do not specify a skin, Kony default skin is applied. e. Select the Header that must be used for the Pivot View. If you do not specify a header, then no header is applied to the Pivot View. Note: The header and footers of the form(s) within the sequence will remain intact. f. Select the Footer that must be used for the Pivot View. If you do not specify a footer, then no footer is applied to the Pivot View. g. Select Show app level headers, footers to indicate if the global headers and footers of the form (s) within the sequence must be displayed. ii. In the properties area, select the Transitions tab and execute the following steps: a. Select a value for In transition. b. Select a value for Out Transition. c. Select a value for In Transition mode. d. Select a value for Out Transition mode. e. Select a value for Animate Header & Footer. f. Select a value for Mode. For more information about modes, refer the Modes. Copyright © 2012 Kony, Inc. All rights reserved. Page 297 of 785 Working with Windows Phone7 Sequences or Views Kony Studio User Guide - 2.1 The transition effects specify the way a form comes in and goes out of view. For more information about transition effects, see Kony Widget User Guide. iii. Click the Add ( ) button in the bottom pane to add a row to the table. a. Provide a Title for the form. b. Select a Form to be included in the Pivot View. c. Select the i18n Key for the Form Title. Important: One form can be included only in one Sequence (pivot or panorama). Using the same form in multiple sequences throws an error. Important: At least one form must be included in the Pivot View to enable the Finish button. 7. Repeat steps 4 and 5 to add more Pivot Views. 8. Click Finish. 9.2 Defining a Panorama Sequence To define a panorama view, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Properties. The Application Properties dialog appears. 3. Under the Native Application Tab, click the Windows Phone 7 and above subtab. 4. Right-click Panorama Views and select Add Panorama Viewor select Panorama View and click the Add ( ) button. 5. A panorama view is created with a unique ID. Copyright © 2012 Kony, Inc. All rights reserved. Page 298 of 785 Working with Windows Phone7 Sequences or Views Kony Studio User Guide - 2.1 i. In the properties area, select the General tab and execute the following steps: a. The ID is automatically created. Modify the ID if required. Note: The ID of each panorama view in an application must be unique. b. Enter a Title for the Panorama View. c. Select the i18n Key for the Title, if required. d. Select a Skin for the Panorama View. If you do not specify a skin, Kony default skin is applied. e. Select the Header that must be used for the Panorama View. If you do not specify a header, then no header is applied to the Panorama View. Note: The header and footers of the form (s) within the sequence will remain intact. f. Select the Footer that must be used for the Panorama View. If you do not specify a footer, then no footer is applied to the Panorama View. g. Select Show app level headers, footers to indicate if the global headers and footers of the form (s) within the sequence must be displayed. ii. In the properties area, select the Transitions tab and execute the following steps: a. Select a value for In transition. b. Select a value for Out Transition. c. Select a value for In Transition mode. d. Select a value for Out Transition mode. e. Select a value for Animate Header & Footer. f. Select a value for Mode. For more information about modes, refer the Form Platform Specific Properties section in the Widget User Guide. The transition effects specify the way a form comes in and goes out of view. For more information about transition effects, see Kony Widget User Guide. iii. Click the Add ( ) button in the bottom pane to add a row to the table. a. Provide a Title for the form. b. Select a Form to be included in the Panorama View. c. Select the i18n Key for the Form Title. Important: One form can be included only in one Sequence (pivot or panorama). Using the same form in multiple sequences throws an error. Important: At least one form must be included in the Pivot View to enable the Finish button. 6. Repeat steps 4 and 5 to add more Panorama Views. 7. Click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 299 of 785 Working with Windows Phone7 Sequences or Views Kony Studio User Guide - 2.1 9.3 Using Sequences After you have defined the Pivot Views and Panorama Views and included the necessary forms, you can use these views anywhere in the application based on your requirement. For example, if frmA is included in a Pivot View along with few other forms, you can use that Pivot View by using the following code: form.show (frmA); The whole Pivot View is displayed with frmA highlighted. You can use a Panorama View in the similar way. 9.4 Important Considerations The following are a few implementation details about the Pivot Views or Panorama Views within an application: l l Form methods like preshow and postshow are executed when the form is highlighted in the Pivot View or Panorama View Events like transactionaldataload and masterdataload are executed when the form is shown for the first time in the Pivot View or Panorama View. 9.5 Limitations The following are the limitations of sequences in Windows Phone 7: l l Once a form is included in a sequence (either Pivot or Panorama), it cannot be re-used in any other sequence. A form that is included in a sequence cannot be accessed directly. You can access it only through a sequence. Copyright © 2012 Kony, Inc. All rights reserved. Page 300 of 785 Kony Studio User Guide - 2.1 Working with Quick Preview 10. Working with Quick Preview The Preview button in the Form Designer (next to a form) provides you the ability to preview the current form on any emulator. You can also access Preview button from the context menu on any form. The advantage of this feature is that you can instantly see the changes you made to the form on an emulator, without building the application every time. The Preview allows you to see the appearance of a form on an emulator allowing you to judge the appearance on the actual device. The Preview feature shows only the widgets that have the render property set to true. For widgets like Segmented UI, sample data is used for preview. You can indicate to the IDE to use the sample data for preview. Note: You can use the Quick Preview feature only to view the User Interface of a Form. You cannot use this feature to see the functional aspects of an application. No code can be executed in the preview mode. Note: Internationalization is not supported. 10.1 Prerequisites The following are the prerequisites for the Quick Preview feature: l Check if Security.framework exists in the Finder/<HOME>/VMAppwithKonylib/VMAppWithKonylib.Xcodeproj/ folder on the Macintosh machine where the iPhone emulator is installed. If it does not exist, see iPhone Configuration section for more information on adding that framework. l Verify that the relevant binary files for the application are available under the <workspace>/temp folder. To ensure this, build the application at least once: o During the life-cycle of the project. o When you upgrade to a newer version of IDE or a platform plug-in. 10.2 Platform Support This section lists the platforms on which the Quick Preview feature is supported: Category Native Applications Platforms l iPhone l Android l BlackBerry l J2ME l Windows Phone Copyright © 2012 Kony, Inc. All rights reserved. Page 301 of 785 Kony Studio User Guide - 2.1 Working with Quick Preview Category Platforms l iPhone l Android l BlackBerry Mobile Web l Windows Phone iPad l Android Tablet l Tablet 10.3 iPhone Configuration This section explains the one-time configuration (per machine) you need to do on a Macintosh machine for the Quick Preview feature. 1. Connect to the MAC Machine. 2. Navigate to Finder/<HOME> folder. 3. Open the VMAppWithKonylib.Xcodeproj file. 4. To preview the application, in Xcode, navigate to Preview > iPhone/iPad 5. Click Run. 10.4 Preview Form Use this feature to see the appearance of a form on an Emulator without building the application. It is helpful when you make changes to a form and would like to have an instant preview. To Preview a Form, follow these steps: 1. Go to Applications View. 2. Select the required application. 3. Expand the <application> -> forms -> mobile/tablet. Note: If you open a form designed for mobile, you will see only the mobile platforms in the Preview Platform Selection window. Note: If you open a form designed for tablet, you will see only the tablet platforms in the Preview Platform Selection window. 4. Double-click the required form. The form appears in the Form Designer. 5. To preview the form, perform one of the following actions: l Click the Preview button in the Form Designer (located next to the form). l Select Preview from the Context menu on a form or any widget on the form. Copyright © 2012 Kony, Inc. All rights reserved. Page 302 of 785 Working with Quick Preview l Kony Studio User Guide - 2.1 Select Preview from the Context menu of any widget in the Outline View. 6. Select the platforms on which you want to see the Preview in the Platform Selection window. Copyright © 2012 Kony, Inc. All rights reserved. Page 303 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 7. Click OK. Note: The application should be built at least once on BlackBerry platform. 8. When the code generation for Preview is completed in the Console, go to Emulators View. 9. Right-click the required emulator and click Open in preview. 10.5 Preview on Emulators This section explains how to preview on different emulators after you have selected the corresponding platforms in the Platform selection window as stated in the previous section. 10.5.1 iPhone Emulator To view an application on iPhone/iPad emulator, follow these steps: 1. If you are downloading the plugins manually, download the iphone binaries from the download site provided by Kony and extract them to a folder, say <HOME> . For more information aboutinstalling iPhone plug-in, see Kony Studio Installation Guide. When you use the installer, the binaries are downloaded automatically. 2. Go to Terminal and enter the following commands: cd <HOME> cd VMAppWithKonylib\gen perl extract.pl <URL of app KAR> For example, perl extract.pl http://10.10.4.87:8888/TestAppr?type=ipad cd .. open VMAppWithKonylib.Xcodeproj Note: For ease of development and deployment to an iOS simulator , Kony Studio packages the application and its resources into a simple binary format referred to as KBF (KonyBinaryFormat) , also referred to as KAR (KonyArchive). This file includes all the application resources like application byte code , images, and FFI dependencies. The KBF/KAR file is generated every time a build is performed for the iOS platform. This file is deployed to the local Jetty server in the IDE and can be downloaded via HTTP, for example, http://ipaddressof the system:portno/appnamer/?type=iphone Copyright © 2012 Kony, Inc. All rights reserved. Page 304 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 Note: If there are Jetty connectivity issues when working with Parallels on MAC machine, it is best to use absolute file reference to the KAR file to be extracted, versus via the Jetty Server (KAR file specified as an HTTP url). A given Kony Studio Application's Xcode KAR file is located in your workspace's WebApps directory. If you are using a dual partition Mac/Windows laptop, the absolute file path would look like: perl extract.pl /Volumes/C/Workspace-V4.0.02GA/webapps/GMr/kbf/konyappiphone.KAR 3. Select Scheme as KDebug, KRelease, or Preview. Set the scheme as : l KPreview for previewing the applications. 4. Click Run in Xcode . This action builds and runs the current application. Note: Close the simulator if it is already open before clicking Run. For iPhone 5, you have to perform an additional step. For more information, refer Viewing applications on the iPhone 5 simulator. 5. Click Preview to launch Quick Preview. Copyright © 2012 Kony, Inc. All rights reserved. Page 305 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 6. The simulator opens with Build Succeeded message and the application opens. Note: For information on debugging an application, see the Debugger section. 10.5.2 Android Emulator To Preview on Android Emulator, follow these steps: 1. Go to Emulators View. 2. Right-click the Android emulator and click Open in preview. 3. Unlock the emulator when it launches. 4. Click Menu. A screen with the title," Preview Settings" appears with Auto Preview and Preview as the options (available at the bottom of the emulator). 5. Click Preview. You can see the preview of the form on the emulator. The preview on the emulator is as Copyright © 2012 Kony, Inc. All rights reserved. Page 306 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 shown below: 10.5.3 BlackBerry Emulator To Preview on BlackBerry Storm Emulator, follow these steps: 1. Go to Emulators View. 2. Right-click the Storm emulator and click Open in preview. 3. Navigate to the Downloads folder when the emulator launches. 4. Double-click KonyPreview application to open it. This application is created by default by the Quick Preview feature. Copyright © 2012 Kony, Inc. All rights reserved. Page 307 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 5. The KONY PREVIEW application opens.Enter the IP Address of the machine where the application was built and click Preview to see the preview. Copyright © 2012 Kony, Inc. All rights reserved. Page 308 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 6. The preview on Storm emulator is as shown below: Important: Load the cod file manually for JS application in the below path specified <<workspace name>>\temp\Application\build\luaj2me\blackberry47\dist\ and BB emulator preview works only if the app is built at least once. 10.5.4 Windows Phone Emulator To Preview on Windows7 Emulator/Desktop, follow these steps: 1. Go to Emulators View. 2. Right-click the WindowsPhone 7/Windows 7 (under Desktop) emulator and click Open in preview. 3. When the emulator launches, you see the Preview Details screen. i. Enter the IP Address (IP address of the machine on which the application is developed). ii. Enter the Port number. The default port is 8888. Copyright © 2012 Kony, Inc. All rights reserved. Page 309 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 4. Click Submit. 5. The preview appears as shown below:. To view the application on Windows 8 Tablet emulator refer Viewing the application on an emulator. 10.5.5 Mobile Web Important: Preview for Mobile Web is not supported for JavaScript applications. To Preview on Mobile Web, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 310 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 1. Launch an Emulator (for example, iPhone or Android) and open the browser. 2. To preview, enter the address in the following format: http://<IP Address of the machine where the app is built>:8888/preview/p 3. The preview is as shown below: 10.5.6 iPad Emulator To Preview on iPad Emulator, follow these steps: 1. Connect to the MAC machine where the emulator is configured and installed. 2. Navigate to <HOME>/Preview folder. 3. Open the VMAppPreview.Xcodeproj file. 4. Click Build and Run. The emulator opens. l Enter the IP Address (IP address of the machine on which the application is developed) and the Port number in the initial screen on the emulator. 5. Click Submit. 6. The preview appears as shown. 10.5.7 Android Tablet Emulator To Preview on Android Emulator, follow these steps: 1. Go to Emulators View. 2. Right-click the Galaxy Tab (or any other tablet emulator if it exists) emulator and click Open in preview. 3. Unlock the emulator when it launches. Copyright © 2012 Kony, Inc. All rights reserved. Page 311 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 4. Click Menu. A screen with the title You are In Quick Preview Mode appears with Quick Preview and Settings as the options (available at the bottom of the emulator). 10.6 Refresh Emulators for Modifications Previewing after making modifications to the form or the widgets is easy. Note: The procedure given below assumes that the emulators are open. To Preview after modifications, follow these steps: 1. On Android and Android Tablet emulator, click Menu -> Quick Preview to refresh the form and see the changes. 2. On BlackBerry (Storm) emulator, click Menu -> Quick Preview to refresh the form and see the changes. 3. On Windows7 emulator, click the Back button on Windows 7 emulator to refresh the form and see the changes. 4. On iPhone emulator, double-click the emulator to launch the menu. Click Refresh App to refresh the form and see the changes. 5. On Mobile Web, you must re-enter the address in the browser in the following format to see the changes: http://<IP Address of the machine where the app is built>:8888/preview/p 10.6.1 Windows 8 features Microsoft Windows 8 has 3 major flavors. Kony supports both Lua and JS as development languages to create native apps for all the flavors of windows 8. The following Microsoft Windows 8 platforms are supported: l Microsoft Windows 8 on Intel chipset (desktop machines, Intel based surface tablets (scheduled to be released this month sometime)). o l Microsoft Windows 8 on ARM chipset ( MS surface, ultrabooks) o l If you want to build native apps for these machines using Kony, you can do it either from windows 7 desktop or windows 8 desktop OS. If you want to build native apps for these machines using Kony you must have Kony studio on windows 8 desktop OS. Microsoft Windows 8 on x64 ( mac ,parallels with windows 8) (to be released in 5.0.05) o If you want to build native apps for these machines using Kony you can do it either from windows 7 desktop or windows 8 desktop OS. For Windows Phone 8 native apps: We support both Lua and JS. Hybrid, Mixed mode are not supported. Copyright © 2012 Kony, Inc. All rights reserved. Page 312 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 For Windows phone 7.5 (a.k.a Mango): We support both Lua and JS. Hybrid, Mixed mode are not supported. Microsoft has also released a new version, Windows phone 7.8, and this version release is only for Mango devices. This version does not have any new features except the start screen change. Microsoft wants to have a consistent look for the start screen across Windows phones. Going forward there will be only two versions of Windows Phone. l Windows phone 8 and above for High end phones (HTC 8x, Lumia 920 etc). l Windows phone 7.8 for Mid-range phones (Lumia 800, Samsung Focus etc). 10.6.2 Viewing an Application on Windows Phone 8 This section lists the procedure for viewing an application on a Windows 8 Phone. You can test the applications only on a Windows 8 system. To build application for Windows 8, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Build. 3. Select an appropriate Build option. 4. Select Windows 8 from Phone and build the application. 5. When the application is built successfully a success message appears on the Console. 6. You can view the built file at the following location: <Drive>\<Workspace>\temp\<AppID>\build\winphone8. Viewing the Application on the Emulator All the emulator setup and requirements are listed at Emulator Setup and Requirements. 1. Right-click the application and build it for Windows Phone 8. 2. The built executable is available at workspace\temp\appname\build\winphone8. 3. Copy the WindowsPhone8.xap file and paste it at any location on a system having a Windows 8 OS. 4. Launch the Application deployment tool. For more information about the Application Deployment tool refer Application Deployment. Copyright © 2012 Kony, Inc. All rights reserved. Page 313 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 5. From the Target drop-down list, select the target emulator on which you want to view your application. 6. Browse for the location where the xap file has been copied to as mentioned in step 3. 7. Click Deploy. 8. If you set the Build mode in IDE as l Debug mode: The IDE automatically launches a Windows Platform Logger when you build the application in the debug mode. An IP Address and Port are listed below in the logger. Copyright © 2012 Kony, Inc. All rights reserved. Page 314 of 785 Working with Quick Preview Kony Studio User Guide - 2.1 Enter the IP address and the port listed in the following window that appears. If you want to debug the application then click on "Connect to logger" by providing the corresponding IP address and the port to which the logger is listening to. Click on "Start without logger" , if you want to launch the application without the logger. l Release mode: When you launch the application in the release mode, the application is launched on the emulator directly. Copyright © 2012 Kony, Inc. All rights reserved. Page 315 of 785 Kony Studio User Guide - 2.1 Working with Automatic Preview 11. Working with Automatic Preview The Automatic Preview feature provides you the ability to preview the current form on any emulator or device when: l A form is saved, l A skin is changed, l There are any changes in an Appmenu. The advantage of this feature is that you can instantly see the changes you made to any saved form on an emulator, without building the application every time. This feature allows you to see the appearance of a form on an emulator or a device. This feature shows only the widgets that have the render property set to true. For widgets like Segmented UI, sample data is used for preview. You can indicate to the IDE to use the sample data for preview. Important: Automatic Preview works only for JavaScript applications. Automatic Preview Quick Preview Quick Preview requires you to click the Preview button The Automatic Preview feature instantly enables you to view the following on any every time to view emulator or a device: Changes made to a form on a form save, skin change, or a any UI changes, change in Appmenu. You do not have to explicitly click Preview every time and choose the choose the platforms for previewing the form on every form change. The only requisite platforms on which being that the desired emulators have to be launched initially for Automatic Preview. you want to preview the changes, and then launch the emulator. Note: You can use the Automatic Preview feature only to view the User Interface of a Form. You cannot use this feature to see the functional aspects of an application. No code can be executed in the preview mode. Note: Internationalization is not supported. 11.1 Prerequisites The following are the prerequisites for the Automatic Preview feature: l Check if Security.framework exists in the Finder/<HOME>/VMAppwithKonylib/VMAppWithKonylib.Xcodeproj/ folder on the MAC machine where the iPhone emulator is installed. If it does not exist, see iPhone Configuration section for more information on adding that framework. l Verify that the relevant binary files for the application are available under the <workspace>/temp folder. To ensure this, build the application at least once: Copyright © 2012 Kony, Inc. All rights reserved. Page 316 of 785 Kony Studio User Guide - 2.1 Working with Automatic Preview o During the life-cycle of the project. o When you upgrade to a newer version of IDE or a platform plug-in. 11.2 Platform Support This section lists the platforms on which the Automatic Preview feature is supported: Category Native Applications Platforms l iPhone l Android l BlackBerry l J2ME l Windows 8 iPad l Android Tablet l Tablet 11.3 iPhone Configuration This section explains the one-time configuration (per machine) you need to do on a MAC machine for the Automatic Preview feature. 1. Connect to the MAC Machine. 2. Navigate to Finder/<HOME> folder. 3. Open the VMAppWithKonylib.Xcodeproj file. 4. To preview the application, in Xcode, navigate to Preview > iPhone/iPad 5. Click Run. 11.4 Configuring Automatic Preview for a Form Use this feature to see the appearance of a form on an Emulator or a device without building the application. It is helpful when you make changes to a form and would like to have an instant preview. The Automatic Preview feature is disabled by default. To configure Automatic Preview for a form, follow these steps: 1. Run an eclipse.exe -clean command in the command prompt. 2. Navigate to the Kony Perspective. Copyright © 2012 Kony, Inc. All rights reserved. Page 317 of 785 Working with Automatic Preview Kony Studio User Guide - 2.1 3. In the Form Designer view, double click the Auto Preview button. The following window appears. 4. The Enable Automatic Preview check box is disabled by default. Select the check box to enable the Automatic Preview feature. 5. The default configured port is 9091. 6. To check whether the configured port is available and is not being used by another application, click Check Port Availability. 7. To select the platforms for which an automatic preview would be generated on every form save, click Configure platforms for Automatic Preview. 8. Select the desired platforms. 9. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 318 of 785 Working with Automatic Preview Kony Studio User Guide - 2.1 10. Click OK to finish. The Automatic Preview feature is enabled. 11. Navigate to Window > Show View. 12. Type Auto in the text field provided. 13. Select Kony Auto Quick Preview Console. 14. Click OK.The Kony Auto Quick Preview Console appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 319 of 785 Working with Automatic Preview Kony Studio User Guide - 2.1 11.5 Preview on Emulators This section explains how to preview on different emulators after you have selected the corresponding platforms in the Platform selection window as stated in the previous section. 11.5.1 iPhone Emulator To view an application on iPhone/iPad emulator, follow these steps: 1. If you are downloading the plugins manually, download the iphone binaries from the download site provided by Kony and extract them to a folder, say <HOME> . For more information aboutinstalling iPhone plug-in, see Kony Studio Installation Guide. When you use the installer, the binaries are downloaded automatically. 2. Go to Terminal and enter the following commands: cd <HOME> cd VMAppWithKonylib\gen perl extract.pl <URL of app KAR> For example, perl extract.pl http://10.10.4.87:8888/TestAppr?type=ipad cd .. open VMAppWithKonylib.Xcodeproj Note: For ease of development and deployment to an iOS simulator , Kony Studio packages the application and its resources into a simple binary format referred to as KBF (KonyBinaryFormat) , also referred to as KAR (KonyArchive). This file includes all the application resources like application byte code , images, and FFI dependencies. The KBF/KAR file is generated every time a build is performed for the iOS platform. This file is deployed to the local Jetty server in the IDE and can be downloaded via HTTP, for example, http://ipaddressof the system:portno/appnamer/?type=iphone Note: If there are Jetty connectivity issues when working with Parallels on MAC machine, it is best to use absolute file reference to the KAR file to be extracted, versus via the Jetty Server (KAR file specified as an HTTP url). A given Kony Studio Application's Xcode KAR file is located in your workspace's WebApps directory. If you are using a dual partition MAC/Windows laptop, the absolute file path would look like: perl extract.pl /Volumes/C/Workspace-V4.0.02GA/webapps/GMr/kbf/konyappiphone.KAR 3. Select Scheme as KDebug, KRelease, or Preview. Set the scheme as : Copyright © 2012 Kony, Inc. All rights reserved. Page 320 of 785 Working with Automatic Preview l Kony Studio User Guide - 2.1 KPreview for previewing the applications. 4. Click Run in Xcode . This action builds and runs the current application. Note: Close the simulator if it is already open before clicking Run. For iPhone 5, you have to perform an additional step. For more information, refer Viewing applications on the iPhone 5 simulator. 5. Verify the details for AutoPreview. 6. Click Auto Preview Connect. 7. As soon as the connection between the emulator and the IDE is established, you can view the details in the Auto Preview console. 8. Any subsequent changes to the form, appmenu or skin in IDE are reflected on the emulator automatically on a form save. 11.5.2 Android Emulator To Preview on Android Emulator, follow these steps: 1. Go to Emulators View. 2. Right-click the Android emulator and click Open in preview. Copyright © 2012 Kony, Inc. All rights reserved. Page 321 of 785 Working with Automatic Preview Kony Studio User Guide - 2.1 3. Unlock the emulator when it launches. 4. Click Menu. A screen with the title," Preview Settings" appears with Preview Settings and AutoPreview Settings as the options (available at the bottom of the emulator). Copyright © 2012 Kony, Inc. All rights reserved. Page 322 of 785 Working with Automatic Preview Kony Studio User Guide - 2.1 5. Select Auto Preview Connect to enable auto preview. 6. As soon as the connection between the emulator and the IDE is established, you can view the details in the Auto Preview console. 7. Any subsequent changes to the form, appmenu or skin in IDE are reflected on the emulator automatically on a form save. 11.5.3 BlackBerry Emulator To Preview on BlackBerry Storm Emulator, follow these steps: 1. Go to Emulators View. 2. Right-click the Storm emulator and click Open in preview. 3. Navigate to the Downloads folder when the emulator launches. 4. Double-click KonyPreview application to open it. This application is created by default by the Automatic Preview feature. Copyright © 2012 Kony, Inc. All rights reserved. Page 323 of 785 Working with Automatic Preview Kony Studio User Guide - 2.1 5. The KONY PREVIEW application opens. Click AutoPreview Connect to see the preview. 6. As soon as the connection between the emulator and the IDE is established, you can view the details in the Auto Preview console. 7. Any subsequent changes to the form, appmenu or skin in IDE are reflected on the emulator automatically on a form save. 11.5.4 Windows 8 Emulator To Auto Preview an application for Windows phone 8: Copyright © 2012 Kony, Inc. All rights reserved. Page 324 of 785 Kony Studio User Guide - 2.1 Working with Automatic Preview 1. Start/Open an application in eclipse (on Windows 7/ windows 8) 2. Build application at least once so that it creates required files in build location. 3. Copy the XAP from this location <eclipseWorkspace>\temp\<Eclipse project name>\build\winphone8\JS into the remote machine. 4. Load the xap file using application deployment. To Auto Preview an application for WindowsTablet: Using this mechanism, windows 8 apps can be tested on x86/x64/ARM based windows 8 systems. IDE may run on Windows 7 or on Windows 8. 1. Start/Open an application in eclipse (on Windows 7/ windows 8). 2. Build application at least once so that it creates required files in build location. 3. Copy "Windows8" folder from "<EclipseWorkspace>\temp\<Eclipse project name>\build" to the target Windows 8 system (x86/x64/ARM based desktop/tablet). 4. Open command prompt in target system and navigate to copied folder. 5. Navigate to Windows8 subfolder. 6. Run below commands to launch preview. Preview setup Development language - target platform architecture - with/ without simulator. JS - x86 - Local system JS - x86 - Simulator JS - x64 - Local system JS - x64 - Simulator JS - ARM - Local system LUA - x86 - Local system LUA - x86 - Simulator LUA - x64 - Local system LUA - x64 - Simulator LUA - ARM - Local system Command previewpackage.bat JS previewpackage.bat JS "simulator" previewpackage.bat JS_x64 previewpackage.bat JS_x64 "simulator" previewpackage.bat JS_ARM previewpackage.bat Lua previewpackage.bat Lua "simulator" previewpackage.bat Lua_x64 previewpackage.bat Lua_x64 "simulator" previewpackage.bat Lua_ARM Copyright © 2012 Kony, Inc. All rights reserved. Page 325 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 12. Integrating Third-party Libraries Using FFI Foreign Function Interface (FFI) is a mechanism that provides support for the application written in one programming language to use the methods, functions, and services written in another programming language. FFI leverages this mechanism to invoke native SDK functions from the JavaScript language runtime infrastructure while building the application in the IDE. FFI is also used to integrate third-party tools such as Web Trends, Omniture, and so on. To view FFI implementation video, see http://docs.kony.com/video_tutorials/Default.htm#RootDetector.htm Important: If you pick up an application that already exists, explicitly generate the code if it is not present. 12.1 Advantages/Limitations FFI feature has the following advantages: l l Methods or functions available in the native SDK can be readily leveraged instead of re-creating the entire functionality in the application. Third party Mini application can also be integrated in the Kony application using FFI, For e.g. if a third party library provides a bar code scanning library (with its own UI and screens) such an app can be invoked from a Kony form. In summary once the control is given to the third party library it can show its own screens / forms as well. Using callbacks the user can also return back to the Kony form from a third party screen. FFI has the following limitations: l l The third-party library for Windows Phone should be a Windows Phone Class Library. If the third-party library belongs to any other library, the build generation will fail on Windows Mobile. On JDK versions prior to 1.5, you have to explicitly typecast boolean to Boolean. From JDK 1.5 onwards, the typecasting is done automatically. l Custom widgets cannot be consumed through FFI. l Importing custom native types such as structures or classes is not supported currently. l Importing the native C based functions for platforms like iPhone is not supported currently. 12.2 Prerequisites/Assumptions Make sure the following software is installed: l Java Development Kit (JDK) on the local machine l .NET Framework 4.0 on the target machine on which you will run the application. The following are the assumptions for Foreign Function Interface feature in the IDE: Copyright © 2012 Kony, Inc. All rights reserved. Page 326 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 1. The metadata is applicable across all platforms. This is because the IDE assumes that for a given functionality, the binaries of different platforms adhere to similar signature. 2. The native methods that are accessed are public methods. 12.3 FFI Approach The following diagram illustrates the approach of FFI: 12.4 Using FFI for JavaScript Projects This section lists the JavaScript datatypes mapped across platforms, procedures for integrating a third party library, adding a class, adding a function, and invoking JavaScript methods. 12.4.1 JavaScript Datatypes This section provides information about the datatypes for the FFI feature: l JavaScript data types are represented as Object counter parts in the Native SDK as against primitive types. For example, java.lang.Double is used instead of double and java.lang.Boolean instead of boolean. Copyright © 2012 Kony, Inc. All rights reserved. Page 327 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI l JavaScript numbers are represented as Objects in native SDK. For example, java.lang.Double in Java, NSNumber in iPhone and so on. l The conversion between the Object and primitive types happens automatically on Android platform. l On BlackBerry platform, if the JavaScript type is number, you need to specify the exact primitive type. The following table explains the datatype mapping in different languages: JavaScript Type Number String Boolean Array Object Function void Objective -C Type Java Type int, long,float, double , int, long,float, java.lang.Integer, double, NSNumber java.lang.Long, (Depending on the java.lang.Double, metadata provided) java.lang.Float(Depending on the metadata provided) NSString java.lang.String BOOL(primitive) java.lang.Boolean, boolean NSArray java.util.Vector java.lang.Object, NSDictionary, id java.lang.Hashtable Callback com.kony.vm.Function void void C# Type int, long, double (Depending on the metadata provided) String bool (primitive) System.Collections.GenericList object Closure void 12.4.2 Adding Third-party Libraries Integrate the third-party custom libraries with the IDE to generate XML files. The IDE uses these XML files as input and generates the platform specific Stub templates, which in turn are used by the Lua or JavaScript runtime infrastructure to invoke native SDK methods. To integrate the third-party libraries with Kony Studio for a JS project, follow these steps: 1. Go to Applications View. 2. Right-click the required application and select Integrate Third Party > Manage Custom Library. The Custom Libraries window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 328 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 3. Right-click JavaScript FFI Definition and select Add JavaScript Namespace. 4. Select . 5. Enter a name for the namespace. Note: The namespace name must be unique and should not be a part of the Kony system namespace. The namespace cannot start with the word kony. 6. Right-click the namespace and do any of the following: l l Select Add JavaScript Class to add a class. A class is the blueprint from which individual objects are created as represented in the external library. In an external library it has only instance methods. Select Add JavaScript Function to add a function. A function represents a utility method exposed by the external library and can be accessed without creating individual objects. Copyright © 2012 Kony, Inc. All rights reserved. Page 329 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI After adding a class, do the following: 1. Expand the namespace and select . 2. In the JavaScript Definition tab, enter a name for the created class. The name of a class cannot begin with the name kony. When you create a class, you create an object of that class. 3. Add the constructor parameters for the class. The possible data types for the constructor parameters are String, Boolean, Number, Array, Object or Function. The Sample invocation code block provides a sample snippet for how the class is invoked. Note: This method does not have any application logic attached to it. Copyright © 2012 Kony, Inc. All rights reserved. Page 330 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI 4. You can add parameters rows by clicking row and clicking . You can remove parameters by selecting a parameter . You can change the order in which parameters are passed by selecting the up or down arrows. You can insert a new parameter before another parameter by clicking insert a new parameter after a parameter by clicking . You can . Note: You must select the native datatype that corresponds to each input parameter. 5. In the Native Mapping tab, perform mapping of the parameter for every platform. The mapping is an essential step as it associates the JS object with the actual object specified for each individual platform. During runtime, this information is used to invoke the corresponding platform specific native method. Note: If you do not map the Javascript object at least on one platform, an empty <mappings> element is created in the corresponding XML file. For more information, see the sample XML file. i. Click Manage libraries icon ( appears as shown below: ) to load the third-party library. The Import libraries window Click Import and browse the required jar file (s). Copyright © 2012 Kony, Inc. All rights reserved. Page 331 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI ii. Or select a Library from the drop-down list. Note: Only the libraries that are imported appear under the drop-down list. iii. For BlackBerry platform, Kony Studio allows you to select different jar files for different versions. Note: Import the required jar files and select the corresponding version. If you do not select any jar file for a given version, the common jar file is considered for that version. iv. The following table shows the acceptable custom library formats that you can load for individual platforms: Platform iPhone Library File Format .zip file (the zip file should have at least one .a file and one .h file; else the IDE does not accept the zip file and displays an error) Android .jar file .jar file Note: This .jar file has to be compatible with Java 1.2. BlackBerry If you are providing different JAR files for different Blackberry versions then ensure that the JAR file names are the same across versions Ensure that the class files are compiled using the following JAVAC Flags: javac -target "1.1" -source "1.2" Windows Mobile .dll file .jar file Note: This .jar file has to be compatible with Java 1.2. J2ME Ensure that the class files are compiled using the following JAVAC Flags: javac -target "1.1" -source "1.2" iPad .zip file (the zip file should have at least one .a file and one .h file; else the IDE does not accept the zip file and displays an error) Copyright © 2012 Kony, Inc. All rights reserved. Page 332 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 v. For Android, BlackBerry, and Windows Phone 7, specify the required Package name that is part of the loaded library. vi. For iPhone, specify the required Framework name that comprises the libraries. You can specify multiple frameworks using a comma separator. vii. Specify the Class name. This class should exist in the package / framework specified in the previous step. The class name corresponds to the native class on the platform. viii. Select Static if you want to define the method as a static method exclusively. Note: By default, any method is a non-static method, i.e., an instance method. An instance method is associated with an object. You should use <objectname>.<methodname> to invoke an instance method. Note: A static method is associated with a class. You should use <classname>.<methodname> to invoke a static method. ix. Specify the Method name. This method should be part of the class specified in step iii. The method should have an application logic defined. Note: The method you specify here should have a one-one correspondence with the JaveScript method signature, i.e., the number of input parameters, the sequence in which they are passed, and the return value should exactly be the same for both the methods without any deviation. Important: If there is no one-one correspondence between the methods, Kony Studio throws an error at build time. For example, the add JS method is mapped to the testMethod on Android platform. When you invoke the add method in any JS code module, the testMethod of native language is invoked internally on Android platform. i.e., the application logic associated with testMethod is executed. x. To copy the mapping created for the mobile platform to the tablet channel or vice versa, rightclick the platform name and select Copy mapping to xxx. xi. The method parameters defined in step 3 are automatically populated. Select the Native type for each of the input parameters. The Native method signature block, displays the native signature of the object on the native platform. Copyright © 2012 Kony, Inc. All rights reserved. Page 333 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 6. Additionally you can add methods to a class. The methods within the class are non-static. The created method should belong in the same parent class. Note: By default, any method is a non-static method, i.e., an instance method. An instance method is associated with an object. You should use <objectname>.<methodname> to invoke an instance method. i. Right-click the created class and select Add JavaScript Method. ii. In the JavaScript Definition tab, select the Return type of the method. iii. Specify the name of the created method and specify parameters within the Parameters area as mentioned in step 3. iv. In the Native Mappings tab, specify the method name of the method on the native platforms. v. Select the Return type per platform. The Return type list is populated based on the Return Type selection made in the JavaScript Definition tab. vi. Select the Native types for each of the input parameters. 7. Repeat steps 2 to 4 and add other methods (if any). 8. Click Finish. A confirmation window appears. Select the appropriate option based on your requirement. Copyright © 2012 Kony, Inc. All rights reserved. Page 334 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI When you click Finish, the FFI configuration is done in the background. As a part of the configuration, an XML file is generated for every namespace. For information about the location of the XML files and generated Stub templates, see FFI Directory Structure. Note: XML files are independent of platforms, whereas the generated Stub templates are platform dependent, i.e., there is one Stub template per platform. You can edit the generated Stub templates manually, if required. Adding a JavaScript function, execute the following 1. Expand the namespace and select . 2. In the JavaScript Definition tab, select the Return type of the JavaScript function. 3. In the JavaScript Definition tab, enter a name for the created function. 4. Add the input parameters for the method. The possible data types for the input parameters are String, Boolean, Number, Array, Object or Function. The Sample invocation code block provides a sample snippet for how the class is invoked. 5. You can add parameters rows by clicking row and clicking . You can remove parameters by selecting a parameter . You can change the order in which parameters are passed by selecting the up or down arrows. You can insert a new parameter before another parameter by clicking insert a new parameter after a parameter by clicking . You can . Note: You must select the native datatype that corresponds to each input parameter. Copyright © 2012 Kony, Inc. All rights reserved. Page 335 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI 6. In the Native Mapping tab, perform mapping of the functions for every platform. The mapping is an essential step as it associates the JS method with the actual function specified for each individual platform. During runtime, this information is used to invoke the corresponding platform specific native method. Note: If you do not map the JavaScript method at least on one platform, an empty <mappings> element is created in the corresponding XML file. For more information, see the sample XML file. i. Click Manage libraries icon ( appears as shown below: ) to load the third-party library. The Import libraries window Click Import and browse the required jar file (s). ii. Or select a Library from the drop-down list. Note: Only the libraries that are imported appear under the drop-down list. iii. For BlackBerry platform, Kony Studio allows you to or select different jar files for different versions, if required. Note: Import all the required jar files and select the corresponding version. If you do not select any jar file for a given version, the common jar file is considered for that version. Copyright © 2012 Kony, Inc. All rights reserved. Page 336 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI iv. The following table shows the acceptable custom library formats that you can load for individual platforms: Platform iPhone Library File Format .zip file (the zip file should have at least one .a file and one .h file; else the IDE does not accept the zip file and displays an error) Android .jar file .jar file Note: This .jar file has to be compatible with Java 1.2. BlackBerry If you are providing different JAR files for different Blackberry versions then ensure that the JAR file names are the same across versions Ensure that the class files are compiled using the following JAVAC Flags: javac -target "1.1" -source "1.2" Windows Mobile .dll file .jar file Note: This .jar file has to be compatible with Java 1.2. J2ME Ensure that the class files are compiled using the following JAVAC Flags: javac -target "1.1" -source "1.2" iPad .zip file (the zip file should have at least one .a file and one .h file; else the IDE does not accept the zip file and displays an error) v. For Android, BlackBerry, and Windows Phone 7, specify the required Package name that is part of the loaded library. vi. For iPhone, specify the required Framework name that comprises the libraries. You can specify multiple frameworks using a comma separator. vii. Specify the Class name. This class should exist in the package / framework specified in the previous step. The class name corresponds to the native class on the platform. viii. By default, any function is a static method, i.e., an instance method. An instance method is associated with an object. You should use <objectname>.<methodname> to Copyright © 2012 Kony, Inc. All rights reserved. Page 337 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 invoke an instance method. Note: A static method is associated with a class. You should use <classname>.<methodname> to invoke a static method. ix. Specify the Method name. This method should be part of the class specified in step iii. The method should have an application logic defined. Note: The method you specify here should have a one-one correspondence with the JaveScript method signature, i.e., the number of input parameters, the sequence in which they are passed, and the return value should exactly be the same for both the methods without any deviation. Important: If there is no one-one correspondence between the methods, Kony Studio throws an error at build time. For example, the add JS method is mapped to the testMethod on Android platform. When you invoke the add method in any JS code module, the testMethod of native language is invoked internally on Android platform. i.e., the application logic associated with testMethod is executed. x. The method parameters defined in step 3 are automatically populated. Select the Native type for each of the input parameters. The Native method signature block, displays the native signature of the function on the native platform. 7. Repeat steps to add other functions (if any). Copyright © 2012 Kony, Inc. All rights reserved. Page 338 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 8. Click Finish. A confirmation window appears. Select the appropriate option based on your requirement. When you click Finish, the FFI configuration is done in the background. As a part of the configuration, an XML file is generated for every namespace. For information about the location of the XML files and generated Stub templates, see FFI Directory Structure. Note: XML files are independent of platforms, whereas the generated Stub templates are platform dependent, i.e., there is one Stub template per platform. You can edit the generated Stub templates manually, if required. Note: If you have existing libraries, XML files, and stub templates, you can import files directly without integrating the library files into the application. For more information, refer Importing library files. 12.4.3 Invoking JavaScript Classes You can invoke the JavaScript Classes defined through FFI in the code modules. Use the following syntax to invoke the JavaScript class(integrated or imported): <variable classobject> = <JavaScriptnamespace>.<class_namespace> (<input parameters>) The methods mapped through the FFI functionality return the following: l result 12.4.4 Invoking JavaScript Functions You can invoke the JavaScript Functions defined through FFI in the code modules. Use the following syntax to invoke the JavaScript function (integrated or imported): <variable returnedvalue> = <JavaScriptnamespace>.<function_ namespace> (<input parameters>) The methods mapped through the FFI functionality return the following: l result 12.4.5 Importing FFI Files If you have the libraries, XML files, and Stub templates already existing, you can import FFI related files into the application rather than integrating them with the application. The advantages of importing are: Copyright © 2012 Kony, Inc. All rights reserved. Page 339 of 785 Integrating Third-party Libraries Using FFI l you do not need to define the methods and bind them to various platforms l you can re-use the existing FFI related files in another application. Kony Studio User Guide - 2.1 When you import the FFI related files, ensure that you import a zip file that contains the customlibs folder (along with its sub-folders). To import FFI related files (the libraries, XML files and Stub templates), follow these steps: 1. Go to Applications View. 2. Right-click the required application and select Import > Custom Libraries. 3. Select the appropriate option on the Warning that appears. 4. Browse and locate the appropriate zip file (that has libraries, XML files, and Stub templates) in the Open window. 5. Click Finish. The library along with other contents is imported into the IDE and is ready for use. Note: As the JavaScript methods defined in the imported library have already been mapped on various platforms, you can straight away start using the methods. 12.4.6 Exporting FFI Files If you want to use the FFI files of one application in another application, you should export the FFI related files. The exported files (a zip file) can be used in another application by importing them. The FFI related files are exported in zip format with the project_ffi.zip to the selected folder. To export FFI related files, follow these steps: 1. Go to Applications View. 2. Right-click the required application and select Export > Custom Libraries. 3. Click Yes on the Confirmation window to confirm. 4. Browse and select the destination folder. 5. Click OK. The FFI related files are exported to the selected folder as project_ffi.zip file. 12.4.7 Building and Packaging the Final Executable When you build the application, the third-party libraries (custom libraries you have loaded) and the generated Stub templates are packaged along with the application binary. If there are any errors during the Build process, the errors are displayed on the Console. All the custom libraries are packaged along with the application as they may be inter-dependent on each other. Copyright © 2012 Kony, Inc. All rights reserved. Page 340 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 Note: If you do not want a specific library to be included in the application binary, delete that library from the <workspace>/<application name>/customlibs/lib/<platform> folder. Important: If you delete a library that is in use, the IDE shows an error during Build generation. 12.4.8 FFI Directory Structure for JavaScript This section explains the directory structure involved in saving the FFI related files. FFI related files are stored at the following location on your local machine: <workspace>/<application name>/resources/customlibs. The customlibs directory contains the following resources: l custom libraries l generated XML files l generated Stub templates. l /lib (contains all the loaded custom libraries grouped by platform) l o /android o /ipad o iphone o /winmobile and so on /jsSrc (contains the generated Stub templates grouped by platform). For more information, see the sample Stub template. Copyright © 2012 Kony, Inc. All rights reserved. Page 341 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI l o /android o /blackberry o /winmobile and so on. /jsXml (contains the XML files generated by the IDE - one for each JS namespace). 12.5 Using FFI for Lua Projects This section lists the Lua datatypes mapped across platforms, procedures for invoking a third party library, and invoking methods. 12.5.1 Lua Datatypes This section provides information about the datatypes for the FFI feature: l l Lua data types are represented as Object counter parts in the Native SDK as against primitive types. For example, java.lang.Double is used instead of double and java.lang.Boolean instead of boolean. Lua numbers are represented as Objects in native SDK. For example, java.lang.Double in Java, NSNumber in iPhone and so on. l The conversion between the Object and primitive types happens automatically on Android platform. l On BlackBerry platform, if the Lua type is number, you need to specify the exact primitive type. The following table explains the datatype mapping in different languages: Lua Type Number String Boolean Error Code and Error Message Lua Table Lua Closure (Callback) nil Objective -C Type Java Type C# Type int, float, double (Depending on the metadata provided) NSString Boolean (primitive) int, float, double (Depending on the metadata provided) String Boolean (primitive) int, float, double (Depending on the metadata provided) String Boolean (primitive) NSException Exception Exception NSDictionary or NSArray (Depending on the metadata provided) Lua Closure (Custom Kony Class) nil HashTable or Vector (Depending on the metadata provided) Lua Closure (Custom Kony Class) NULL HashTable or Vector (Depending on the metadata provided) Lua Closure (Custom Kony Class) NULL 12.5.2 Adding Third-party Libraries Integrate the third-party custom libraries with the IDE to generate XML files. The IDE uses these XML files as input and generates the platform specific Stub templates, which in turn are used by the Lua or JavaScript runtime infrastructure to invoke native SDK methods. To integrate the third-party libraries with Kony Studio, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 342 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI 1. Go to Applications View. 2. Right-click the required application and select Integrate Custom Library (FFI). The Custom Libraries window appears as shown below: 3. Right-click Lua Methods and select Add Namespace. 4. Expand Lua Methods and select . 5. Enter a name for the namespace that you have added. Note: The namespace name must be unique and should not be a part of the Kony system namespace. For example, widget, window, segui etc are reserved namespaces and should not be used for third-party libraries. 6. Right-click the namespace and select Add Lua Method to add a method. 7. Expand the namespace and select . 8. Enter a name for the method. Copyright © 2012 Kony, Inc. All rights reserved. Page 343 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI 9. Define the method signature. i.e., the metadata of the Lua method. i. Select the Return type for the method. The possible return values are void, string, boolean, number, or LuaTable. ii. Add the input parameters for the method. The possible data types for the input parameters are string, boolean, number, LuaTable, or Closure. Note: This method does not have any application logic attached to it. Note: You must select the native datatype that corresponds to each input parameter, when you perform the method mapping. 10. Perform mapping of the methods for every platform. The mapping is an essential step as it associates the Lua method with the actual method specified for each individual platform. During runtime, this information is used to invoke the corresponding platform specific native method. Note: If you do not map the Lua method at least on one platform, an empty <mappings> element is created in the corresponding XML file. For more information, see the sample XML file. i. Click Manage libraries icon ( appears as shown below: ) to load the third-party library. The Import libraries window Click Import and browse the required jar file (s). Copyright © 2012 Kony, Inc. All rights reserved. Page 344 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 Important: On BlackBerry platform, while importing the libraries, you have the option to select the BlackBerry version to which the corresponding jar file will be applicable. ii. Or select a Library from the drop-down list. Note: Only the libraries that are imported appear under the drop-down list. iii. For BlackBerry platform, Kony Studio allows you to or select different jar files for different versions, if required. Note: Import all the required jar files and select the corresponding jar files against each version. If you do not select any jar file for a given version, the common jar file is considered for that version. iv. The following table shows the acceptable custom library formats that you can load for individual platforms: Copyright © 2012 Kony, Inc. All rights reserved. Page 345 of 785 Kony Studio User Guide - 2.1 Integrating Third-party Libraries Using FFI Platform iPhone Library File Format .zip file (the zip file should have at least one .a file and one .h file; else the IDE does not accept the zip file and displays an error) Android .jar file .jar file Note: This .jar file has to be compatible with Java 1.2. BlackBerry Ensure that the class files are compiled using the following JAVAC Flags: javac -target "1.1" -source "1.2" Windows Mobile .dll file SPA .js file .jar file Note: This .jar file has to be compatible with Java 1.2. J2ME Ensure that the class files are compiled using the following JAVAC Flags: javac -target "1.1" -source "1.2" iPad .zip file (the zip file should have at least one .a file and one .h file; else the IDE does not accept the zip file and displays an error) v. Specify the required Package name that is part of the loaded library. vi. Specify the Class name. This class should exist in the package specified in the above step. vii. Select static if you want to define the method as a static method exclusively. Note: By default, any method is a non-static method, i.e., an instance method. An instance method is associated with an object. You should use <objectname>.<methodname> to invoke an instance method. Note: A static method is associated with a class. You should use <classname>.<methodname> to invoke a static method. viii. Specify the Method name. This method should be part of the class specified in step iii. The method should have an application logic defined. Copyright © 2012 Kony, Inc. All rights reserved. Page 346 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 Note: The method you specify here should have a one-to-one correspondence with the Lua method signature, that is, the number of input parameters, the sequence in which they are passed, and the return value should exactly be the same for both the methods without any deviation. Important: If there is no one-to-one correspondence between the methods, Kony Studio throws an error at build time. Important: For iPhone and iPad, the number of Methods that are passed in the API should append same number of colons. For example: (return_type) methodNamePart1:(param1_type1)param1 methodnamePart2:(param_type2)param2 methodnamePart3:(param_ type3)param3; You must replace as follows: methodNamePart1: methodnamePart2: methodnamePart3: For example, the add Lua method is mapped to the testMethod on Android platform. When you invoke the add method in any Lua code module, the testMethod of native language is invoked internally on Android platform. i.e., the application logic associated with testMethod is executed. i. Specify the Method name. This method should be part of the class specified in step iii. The method should have an application logic defined. Copyright © 2012 Kony, Inc. All rights reserved. Page 347 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 Note: The method you specify here should have a one-one correspondence with the Lua method signature, i.e., the number of input parameters, the sequence in which they are passed, and the return value should exactly be the same for both the methods without any deviation. Important: If there is no one-one correspondence between the methods, Kony Studio throws an error at build time. For example, the add Lua method is mapped to the testMethod on Android platform. When you invoke the add method in any Lua code module, the testMethod of native language is invoked internally on Android platform. i.e., the application logic associated with testMethod is executed. ix. Select Pass Activity Context Object to method as first parameter to pass Activity Context object as the first Parameter to third-party library methods. This step is applicable only for on Android mobile and tablet platforms. Important: This option appears only if you open an application created in versions prior to 5.0 and it has been selected in projects prior to 5.0. This option is discontinued from 5.0 onwards. For more information on context objects refer Guidelines for Third Party Libraries-Android. x. Select the native Return type of the method when you are doing the mapping. xi. The method parameters defined is step 9 are automatically populated. Select the Native type for each of the input parameters. Copyright © 2012 Kony, Inc. All rights reserved. Page 348 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 11. Define Method Exceptions. i. Add an Error Code and define specify the corresponding Error Type. ii. Repeat the above step for all the possible error code for this method. 12. Repeat steps 6 to 10 and add other methods (if any). 13. Click Finish. A confirmation window appears as shown below: Yes - overwrites the templates if they already exist No - does not overwrite the existing templates. Select the appropriate option based on your requirement. When you click Finish, the FFI configuration is done in the background. As a part of the configuration, an XML file is generated for every namespace. For information about the location of the XML files and generated Stub templates, see FFI Directory Structure. Copyright © 2012 Kony, Inc. All rights reserved. Page 349 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 Note: XML files are independent of platforms, whereas the generated Stub templates are platform dependent, i.e., there is one Stub template per platform. You can edit the generated Stub templates manually, if required. 12.5.3 Invoking Lua Methods You can invoke the Lua methods defined through FFI in the code modules. Use the following syntax to invoke the Lua methods (integrated or imported): <variable> = <namespace>.<method_name> (<input parameters>) The methods mapped through the FFI functionality return the following: l result l error code. Note: The result is LuaNil.nil incase of error. 12.5.4 Importing FFI Files If you have the libraries, XML files, and Stub templates already existing, you can import FFI related files into the application rather than integrating them with the application. The advantages of importing are: l you do not need to define the methods and bind them to various platforms l you can re-use the existing FFI related files in another application. When you import the FFI related files, ensure that you import a zip file that contains the customlibs folder (along with its sub-folders). To import FFI related files (the libraries, XML files and Stub templates), follow these steps: 1. Go to Applications View. 2. Right-click the required application and select Import > Custom Libraries. 3. Select the appropriate option on the Warning that appears. 4. Browse and locate the appropriate zip file (that has libraries, XML files, and Stub templates) in the Open window. 5. Click Finish. The library along with other contents is imported into the IDE and is ready for use. Note: As the JavaScript methods defined in the imported library have already been mapped on various platforms, you can straight away start using the methods. Copyright © 2012 Kony, Inc. All rights reserved. Page 350 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 12.5.5 Exporting FFI Files If you want to use the FFI files of one application in another application, you should export the FFI related files. The exported files (a zip file) can be used in another application by importing them. The FFI related files are exported in zip format with the project_ffi.zip to the selected folder. To export FFI related files, follow these steps: 1. Go to Applications View. 2. Right-click the required application and select Export > Custom Libraries. 3. Click Yes on the Confirmation window to confirm. 4. Browse and select the destination folder. 5. Click OK. The FFI related files are exported to the selected folder as project_ffi.zip file. 12.5.6 Building and Packaging the Final Executable When you build the application, the third-party libraries (custom libraries you have loaded) and the generated Stub templates are packaged along with the application binary. If there are any errors during the Build process, the errors are displayed on the Console. All the custom libraries are packaged along with the application as they may be inter-dependent on each other. Note: If you do not want a specific library to be included in the application binary, delete that library from the <workspace>/<application name>/customlibs/lib/<platform> folder. Important: If you delete a library that is in use, the IDE shows an error during Build generation. 12.5.7 FFI Directory Structure for Lua This section explains the directory structure involved in saving the FFI related files. FFI related files are stored at the following location on your local machine: <workspace>/<application name>/resources/customlibs. The customlibs directory contains the following resources: l custom libraries l generated XML files Copyright © 2012 Kony, Inc. All rights reserved. Page 351 of 785 Integrating Third-party Libraries Using FFI l generated Stub templates. l /lib (contains all the loaded custom libraries grouped by platform) l o /android o /ipad o iphone o /winmobile and so on Kony Studio User Guide - 2.1 /src (contains the generated Stub templates grouped by platform). For more information, see the sample Stub template. o /android Copyright © 2012 Kony, Inc. All rights reserved. Page 352 of 785 Integrating Third-party Libraries Using FFI o /blackberry o /winmobile and so on. Kony Studio User Guide - 2.1 12.6 Guidelines for Third-party Libraries This section explains the guidelines that a third-party library must follow before it is integrated with Kony Studio. 12.6.1 iPhone Prerequisite l Ensure that the library uses the Object versions of primitive types while writing the Hybrids for FFI compatibility. For example, if a number is mentioned in the IDE, the Hybrid should accept NSNumber. l Ensure that namespace for FFI does not clash with the names of the header files in the imported zip file. For example, if the namespace is zxling then there should not be any header file with the name zxling.h. l Ensure that any dependent frameworks are added as part of the Xcode project configuration before building the Xcode project. 12.6.1.1 Invoking callback functions for iPhone To execute a callback from FFI, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 353 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 1. Import Callback.h file into the FFI class. For example: #import "CallBack.h" 2. Following are the two APIs to be called upon Callback object [passed from JavaScript], to execute the JavaScript method, as required. a. (NSArray*) executeWithArguments: (NSArray*) arguments; l arguments: Array containing the parameters to be passed for the JavaScript function. b. (NSArray*) executeWithArguments: (NSArray*) arguments spawn:(BOOL) spawn; l arguments: Array containing the parameters to be passed for the JavaScript function. l spawn: If set to Yes, then Callback is executed on the thread other than the main thread (which is responsible for executing all the JavaScript code). To avoid synchronization problems, it is advised to set asYes. If set to No, then Callback is executed on the thread from which the FFI is called. 3. To execute any functionality asynchronously, FFI can create its own thread using Objective-C, NSThread APIs 12.6.2 Android To develop a third-party Java library and to integrate it with Kony Application using FFI, you need the following .jar files: l konywidgets.jar - to access some classes and methods to communicate back-and-forth between third-party libraries and Kony Platform. This file is located at <workspace>/temp/<app>/build/luaandroid/dist/<app>/libs when you build the application. l android.jar - to access some Android specific APIs or refer Android classes. This file is located at <android-sdk>/platforms/android-<api_level_number> . For more information about API Levels, see http://developer.android.com/guide/appendix/apilevels.html. You must link these two jar files to your third-party Java library project while developing the application. Once you link these two files, you do not need to import these files while integrating Java library with FFI. 12.6.2.1 Invoking callback functions Callback functions that are mapped as parameters to third-party library methods are Function objects. The class Function is present in konywidgets.jar file. To invoke a callback function from third-party library, call callback.execute (new Object[]{param1, param2, ….}) where callback is of type Function and param1, param2 ... are arguments to Lua callback function. The type of those arguments should match type of arguments of corresponding Lua function. If you do not want to pass arguments, call callback.execute with null as the argument. Copyright © 2012 Kony, Inc. All rights reserved. Page 354 of 785 Integrating Third-party Libraries Using FFI The Kony Studio User Guide - 2.1 Context object From 5.0, IDE does not support passing implicit Android Context object ("Pass Context object as first parameter") to the FFI APIs. Application developers (FFI Jar dev) would be able to get the Android context object using one of the following API's which are available in the konywidgets.jar file. l KonyMain.getActivityContext(); l KonyMain.getAppContext(); Do not store the context object locally since the Activity context becomes invalid(null) based on the application state. KonyMain.getActivityContext() can possibly return null, Application developers should check for not null before using it. It is recommended to use "KonyMain.getAppContext()" unless Activity context is specifically required. The JavaScript function The class com.konylabs.vm.Function represents the JavaScript data type "Function". If a callback function takes Luatable as its parameter, while invoking callback in Java create object of LuaTable and insert data into that table and pass it as a parameter to callback. Data can be inserted into LuaTable as key-value pairs using LuaTable.setTable(Object key, Object value) method for both map-part and list-part of Luatable except that in case of map-part, key should be of type string and in listpart key should be an integer. 12.6.2.2 Consuming services offered by Android System or third-party or native applications installed on a Device An application can leverage the services offered by another/same application or Android system itself in an asynchronous manner through Intent mechanism. These services can be in the form of UI or non-UI. In both the cases, some sort of data is returned back to calling application asynchronously as a result. When you want to use services offered by another/same application, you must send an appropriate Intent to Android System. In case of UI, the system handles launching appropriate Activity of an application which can handle this Intent. The system will show a list of Activities if there are more than one which can handle this Intent. In case of non-UI, a listener is registered along with the Intent to the system so that system will broadcast the result to registered listeners. The methods android.content.Context.startActvity() and android.app.Activity.startActivityForResult() can be used to send the intent to system for services involving UI. The former method launches the activity that handles Intent and latter method launches the activity. The launched activity returns the result back to the caller in an asynchronous manner. The method android.content.Context.registerReceiver() can be used to register a listener with the system along with intent for services involving non-UI. For more information about Intents, see http://developer.android.com/guide/topics/intents/intents-filters.html. Copyright © 2012 Kony, Inc. All rights reserved. Page 355 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 See Android API documentation at http://developer.android.com/reference/packages.html. 12.6.2.3 Capturing results of a service involving UI For third-party libraries to capture the results of another/same application's activity, the Kony Android provides an interface named com.konylabs.ffi.ActivityResultListener. The third-party library class must implement and register this interface with the platform through com.konylabs.android.KonyMain.registerActivityResultListener(). Interface Description package com.konylabs.ffi; import android.content.Intent; /** * Callback interface which the client needs to be implemented and registered with * ActivityResultPublisher (a.k.a com.konylabs.android.KonyMain) along with * unique requestCode. */ public interface ActivityResultListener { /** * Callback that is called when some other activity, launched via * Context.startActivityForResult(), exits. * Ensure that requestCode with which callback is being registered should be * the same as the one passed to startActivityForResult(). * Same requestCode will be sent as one of the input parameters. * * @param requestCode - unique token with which this callback was registered. * This should be the same as the one with which an Activity was invoked via startActivityForResult(). * @param resultCode - result code indicating status of the result. Either of Activity.RESULT_ OK or Activity.RESULT_CANCELLED. * @param data - intent data that is passed by the called Activity. */ public void onActivityResult(int requestCode, int resultCode, Intent data); } Interface Registration Method and Description /** * Registers a callback that will be invoked when some other activity, * launched via Context.onActivityForResult() exits. * Ensure that requestCode with which callback is being registered should be * the same as the one passed to startActivityForResult(). Copyright © 2012 Kony, Inc. All rights reserved. Page 356 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 * * @param requestCode - unique token that is mapped to this callback. This * should be the same as the one passed to startActivityForResult(). * * @param activityResultListener - the callback listener which the client * needs to be implemented or null to deregister callback. */ public void com.konylabs.android.KonyMain.registerActivityResultListener( int requestCode, ActivityResultListener activityResultListener); Typical examples where you can use ActivityResultListener to capture result in third-party libraries are to: l get the captured image by launching native camera application. l pick an image or file from native gallery or file explorer application l pick a contact from native phone book application. Apart from these, you can use the services offered by other third-party applications installed in a particular device. 12.6.2.4 Capturing results of a service involving non-UI For third-party libraries to fetch the result of a service involving non-UI, the client Class must register an instance of android.content.BroadcastReceiver with the system along with Intent for which it wants to listen. To register a listener, invoke Context.registerReceiver() and then implement its onReceive() method. For more information about BrodcastReceiver, see http://developer.android.com/reference/android/content/BroadcastReceiver.html. Typical examples where you use BroadcastReceiver to capture result in third-party libraries are: l Knowing battery status like percentage of charge, battery connected or disconnected. l Knowing system shutdown or booting finished l Knowing alarm expiry or timezone changed. Apart from these system-wide notifications sent by Android system, there can be application specific broadcast notifications. Those applications can be native or third-party applications installed on the device. 12.6.2.5 Extracting Result Data The actual result data returned by the invoked Activity (in case of UI) or broadcast message sent (in case of non-UI) to the caller, will be present in Intent object parameter in onActivityResult() or onReceive() method respectively. The type of data that is returned is defined by the invoked Activity or broadcast message sender of a third-party/native application or Android system. Android defines a protocol on how to extract data. for more information, see Intent Data Structure at http://developer.android.com/reference/android/content/Intent.html. Copyright © 2012 Kony, Inc. All rights reserved. Page 357 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 Once the actual data is extracted, pass it back to the Kony Application as parameters to registered JavaScript callback function (optionally) by parsing that data into a type that can be interpreted by the JavaScript code. Intent to select/pick an image or a file //registering current class as an ActivityResultListener for the specified request code. Current class implements ActivityResultListener. ((KonyMain)context).registerActivityResultListener(SELECT_FILE_ REQUEST_CODE, this); Intent intent = new Intent(); intent.setAction(Intent.ACTION_GET_CONTENT); //set the mime-type of content to be selected. For only images specify image/* intent.setType("*/*"); ((Activity)context).startActivityForResult(intent, SELECT_FILE_ REQUEST_CODE); where SELECT_FILE_REQUEST_CODE can be any integer. Same integer is returned as a parameter to onActivityResult(). In onActivityResult(), get the URI of selected image/file from Intent data object as Uri uri = data.getData(). Intent to get the image captured by Camera application //registering current class as an ActivityResultListener for the specified request code. Current class implements ActivityResultListener. ((KonyMain)context).registerActivityResultListener(CAMERA_REQUEST_ CODE, this); //create an empty image file at pre-defined location File capturedImage = new File(FILE_LOCATION_PATH); Uri capturedImageUri = Uri.fromFile(capturedImage); Intent intent = new Intent(MediaStore.ACTION_IMAGE_CAPTURE); //specify the uri at which camera should save the captured image intent.putExtra(MediaStore.EXTRA_OUTPUT, fileUri); ((Activity)context).startActivityForResult(intent, CAMERA_REQUEST_ CODE); where CAMERA_REQUEST_CODE can be any integer. Same integer is returned as a parameter to onActivityResult(). In onActivityResult(), get the URI of captured image from Intent data object as Uri uri = data.getData(). Copyright © 2012 Kony, Inc. All rights reserved. Page 358 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 For more information about Camera including video capture, see http://developer.android.com/guide/topics/media/camera.html. Intent to send an Email Intent emailIntent = new Intent(); emailIntent.setAction(Intent.ACTION_SEND_MULTIPLE); emailIntent.setType("text/plain"); //specify email addresses of primary recipients emailIntent.putExtra(Intent.EXTRA_EMAIL, new String[]{to}); //specify email addresses of secondary recipients emailIntent.putExtra(Intent.EXTRA_CC, new String[]{cc}); //specify email addresses of tertiary recipients emailIntent.putExtra(Intent.EXTRA_BCC, new String[]{bcc}); //specify subject emailIntent.putExtra(Intent.EXTRA_SUBJECT, subject); //specify email body emailIntent.putExtra(Intent.EXTRA_TEXT, message); //specify attachments if any ArrayList<Uri> attachmentUris = new ArrayList<Uri>(); for(String attachment : attachments){ Log.d(TAG,"Attachment: "+attachment); attachmentUris.add(Uri.parse(attachment)); } emailIntent.putParcelableArrayListExtra(Intent.EXTRA_STREAM, attachmentUris); context.startActivity(emailIntent); This intent opens an email client installed on the device capable of handling this intent. This intent does not result any data back to the caller. Intent to pick a contact //registering current class as an ActivityResultListener for the specified request code. Current class implements ActivityResultListener. ((KonyMain)context).registerActivityResultListener(PICK_CONTACT_ REQUEST_CODE, this); Intent intent = new Intent(Intent.ACTION_PICK); //specify URI of the Contacts Table intent.setData(ContactsContract.Contacts.CONTENT_URI); context.startActivityForResult(intent, PICK_CONTACT_REQUEST_CODE); Copyright © 2012 Kony, Inc. All rights reserved. Page 359 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 where PICK_CONTACT_REQUEST_CODE can be any integer. Same integer is returned as a parameter to onActivityResult(). In onActivityResult(), get the URI of selected contact from Intent data object as Uri contactUri = data.getData(). Using ContentResolver and this contactUri get the Cursor object to selected contact as Cursor cursor = context.getContentResolver().query(contactUri, null, null, null, null, null) For more information about retrieving information from cursor and Contacts table, see http://developer.android.com/guide/topics/providers/content-providers.html, http://developer.android.com/reference/android/database/Cursor.html, and http://developer.android.com/reference/android/provider/ContactsContract.Contacts.html. Intent to get the battery status //register a broadcast receiver to receive updates regarding battery status mContext.registerReceiver(mBatInfoReceiver, new IntentFilter(Intent.ACTION_BATTERY_CHANGED)); where mBatInfoReceiver is an instance of class that extends BroadcastReceiver . System will broadcast the information about battery such as charging level, status, and other information about battery to the registered broadcast receivers as intent data to its onReceive() callback. In onRecieve(), retrieve information about battery like charging status, level etc from the intent object passed to it. //get the level of battery charge int level = intent.getIntExtra(BatteryManger.EXTRA_LEVEL, 0); //get the status of battery such as charging, discharging, full, not charging int status = intent.getIntExtra(BatteryManger.EXTRA_STATUS, 0); For more information about Battery, see http://developer.android.com/reference/android/os/BatteryManager.html. Guidelines l The Java Class on which the static method is invoked should have a public default constructor: public class Foo { ......public Foo() Copyright © 2012 Kony, Inc. All rights reserved. Page 360 of 785 Integrating Third-party Libraries Using FFI Kony Studio User Guide - 2.1 ......{ ......} } l A few Android native APIs require access to the Activity class present in the konywidgets.jar file. Ensure that this JAR file is located at <workspace>\temp\<appName>\build \luaandroid\dist\<appName>\libs\ folder. Use the static method com.konylabs.KonyMain.getActContext() to access the current Activity class. l You can reference any of the APIs that are already present on the device (including konywidgets.jar) in the Java projects. But ensure that you do not import these JAR files into Kony Studio. 12.6.3 BlackBerry l The Java Class on which the static method is invoked should have a public default constructor: public class Foo { ......{ ......} } l The library should not have a main method. The main method is the entry point into the BlackBerry application. Kony Studio defines a main method during code generation. Another main method leads to erroneous behavior. public static void main(String[] args) l Ensure that the Java class files are compiled using the following JAVAC Flags: javac -target "1.1" -source "1.2" l Ensure that resultant JAR file is pre-verified using: C:\Program Files\Research In Motion\<JDE FOLDER>>\bin\preverify.exe classpath C:\Program Files\Research In Motion\BlackBerry JDE 4.2.1\lib\net_rim_api.jar <FFI>.jar l l Do not have a class that extends UiApplication interface. If you use a class that extends this interface, the class is not integrated with the IDE and the IDE throws a NoClassDefFoundError. The possible reasons for this error are: o JAR file was not pre-verified o Native Hybrid library refers to a class that extends UiApplication. Do not import the net_rim_api.jar file into Kony Studio. This JAR file has been provided by BlackBerry only for compiling the BlackBerry Desktop Applications. Note: All the methods in all the classes of this JAR file are marked as external (dummy). Copyright © 2012 Kony, Inc. All rights reserved. Page 361 of 785 Integrating Third-party Libraries Using FFI l Check the BlackBerry API documentation available at C:\Program Kony Studio User Guide - 2.1 Files\Research In Motion\<JDE Version>\docs\api to check if the API used in the library is supported. l l You can reference any of the APIs that are already present on the device (including konywidgets.jar) in the Java projects. But ensure that you do not import these JAR files into Kony Studio. Check the *rapc.log file (end of the file) located under <workspace>\temp\<appName>\build\luaj2me\blackberry and <workspace>\temp\<appName>\build\luaj2me\blackberry47 if you get the exec returned error 97 error while building an application for BlackBerry in the IDE. This error indicates that the generation of COD file was not successful from the application JAR file. Copyright © 2012 Kony, Inc. All rights reserved. Page 362 of 785 Kony Studio User Guide - 2.1 Working with Event Editor 13. Working with Event Editor The objective of Event Editor is to perform a set of actions with minimal coding. The Event Editor also reduces dependencies on the programming languages used. The main advantage of using Event Editor is to maintain the code base efficiently. Whenever an event is triggered in the application, you need to specify a set of actions that need to be executed. Event Editor is used to define these action sequences. It is used for the following events: l Form - masterdataload , transactionaldataload, preshow, postshow, and onhide. For more information about form events, see Form Events. l Clickable widgets - onclick , l AppMenu Events. ondone, and so on. Event Editor consists of two components: l Mapping Editor l Expression Builder. For detailed explanation of all the action sequence items, see Action Sequences. 13.1 Launching Event Editor To launch Event Editor, follow these steps: 1. Go to Applications view. 2. Select an application and expand it. 3. Expand forms. 4. Select a form and expand it. 5. Select a widget that can trigger an event. 6. Go to Properties view. 7. Scroll to Event. 8. Select the event for which you want to define an action sequence. 9. Select value and click . Event Editor appears. 10. In the Sequence tab, execute the following: l l Enter Sequence Name. You can use this name to access the action sequence at a later stage. Select Make sequence as global if you want the action sequence to be available globally across the application. Note: Changes made to global action sequences will be reflected across the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 363 of 785 Working with Event Editor l Kony Studio User Guide - 2.1 Define Action Sequences. 11. To view the codes defined in the Event Editor across platforms: a. Click the Generate Code... button. The Select platforms to generate code dialog appears. b. Select the platforms for which you want to view the generated code. c. Click OK. The code defined within the Action Sequences in Event Editor appear. All the code sequences having ifdef statements can be viewed in the Code with ifdef tab. The platform specific codes can be viewed in the <<Platform name>> tab. 13.2 Global Variables and Data Store Keys You can add global variables or data store keys in the Services view. The variables or Data Store keys added here are accessible globally, that is, they are accessible across: l all the forms in the application l code modules Note: All the global variables defined here are accessible in the code modules except Pre-Appinit, but the global variables defined in the code modules are not accessible from the Services view. l Event Editor l Mapping Editor. Note: You can define Data Store keys only from the Services view. Alternatively, you can also add variables in the Event Editor as a part of the action items. The variables added in the Event Editor are local variables and are available only to the action items defined from that point onwards. For more information, see Event Editor. Important: Use global variables only when necessary for better performance of the application. Nullify the global variables when they are not needed anymore. 13.2.1 Adding Global Variables Global Variables are of two types: l l Simple - you can assign data to this variable Collection - this is a data set that has multiple records. You can add as many columns as you want to a collection and then add data to them. Note: Variables are application related. After you logout from the application, the variables are no longer available. To add global variables, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 364 of 785 Working with Event Editor Kony Studio User Guide - 2.1 1. Go to Services view. 2. Right-click Variables. 3. Select Add variable -> Simple to add a normal global variable. The Add window appears as shown below. i. Enter a Name for the variable. ii. Select its Data Type. iii. Enter a Value for the variable. The value you enter in Value: is treated as the default value. The default value is taken into consideration if no other value is assigned to the variable at later point of time in the application. iv. Click OK. Note: Data Type can be string, boolean, or number. 4. Select Add variable -> Collection to add a collection. The Add Variable window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 365 of 785 Working with Event Editor Kony Studio User Guide - 2.1 i. Enter a Name for the collection and click OK. ii. Right-click the collection and select Add Column -> Simple or Collection. This step creates columns within the collection. Note: You can have a collection within a collection. iii. Go to Data tab. All the columns you define in the above step appear here. iv. Click Add to create a row. Enter values under each column. Note: You can add data to a collection only till the second level from the IDE. You can set data to further levels of collection from the code modules. 5. Click OK when you have assigned data to the collection. Note: The variable names should be unique. No two variables can have the same name. 13.2.2 Adding Data Store Keys Data Store keys are used to save data on to the mobile device. Data Store keys are of two types: l Simple - you can assign data to this key. l Collection - you can add as many columns as you want to a collection and then add data to them. Note: The data store keys are available even after you logout of the application. To add data store keys, follow these steps: 1. Go to Services view. 2. Right-click Data Store Keys. 3. Select Add DS Key -> Add Simple Key to add a normal data store key. The Add window appears as shown below. . Copyright © 2012 Kony, Inc. All rights reserved. Page 366 of 785 Working with Event Editor Kony Studio User Guide - 2.1 i. Enter a Name for the variable. ii. Select its Data Type. iii. Select a DataStoreType. This is specific only to Mobile Web. iv. Click OK. 4. Select Add DS Key -> Collection to add a collection. The Add DS Store Key window appears as shown below: i. Enter a Name for the collection. ii. click OK. iii. Select a DataStoreType. 5. Right-click the collection and select Add Column -> Simple or Collection. This step creates columns within the collection. Note: You can define a collection within a collection. 6. Go to Data tab. All the columns you define in the above step appear here. 7. Click Add to create a row. Enter values under each column. 8. Click OK when you have assigned data to the collection. Note: The data store key names should be unique. No two data store keys can have the same name. 13.3 Action Sequences Event Editor consists of a set of actions that can be used to determine what is to be done when an event is triggered. Copyright © 2012 Kony, Inc. All rights reserved. Page 367 of 785 Working with Event Editor Kony Studio User Guide - 2.1 You may want to reuse the action sequence defined for a specific widget. You can reuse this action sequence across widgets within the application. In such a scenario, KonyOne Studio provides you with an option to mark the action sequence as global. Once you mark the action sequence as global, you can invoke that sequence on other widgets without redefining the action sequence. The Event Editor allows you to mark an action sequence as global as shown below: Note: A Global Action Sequence is not tied to any widget, it is independent of the widgets. Event Editor consists of the following action sequence items: Invoke Service (Synchronous) To invoke a synchronous service. Invoke Service (Asynchronous) To invoke an asynchronous service. Navigate to a form/Popup To navigate to a form or Popup. Add Mapping To map data within the same form. In this case, the source and target is the same. Show Alert To display an alert. Alert can be error, information, or confirmation. Add Preprocess Decision To perform a certain action based on the platform on which the application is running. Copyright © 2012 Kony, Inc. All rights reserved. Page 368 of 785 Working with Event Editor Kony Studio User Guide - 2.1 Add Decision To execute an action based on a condition. An action can be specified if the condition evaluates to true, and another action can be specified if the condition evaluates to false. Add Snippet To add a simple code snippet instead of invoking a function. Invoke Function To make a function call. Invoke Sequence To invoke a global action sequence. Add Comment To add a comment within the action sequence. Add Local Variable To add a simple variable or a collection. A collection represents a set of data that is in the form of records. You can add columns to a collection. These columns are known as keys. You can also assign data to the columns. 13.3.1 Enabling or Disabling an Action Sequence You can enable or disable all the Action Sequences or enable or disable a certain snippet, decision, or other specific action sequence items. Enabling or disabling only certain Action Sequences enables you to debug and test only certain action sequences in an application. To enable or disable an action sequence, do the following: 1. Right - click an action sequence and do any of the following: l Select Disable All to disable all the Action sequences in the Editor. l Select Enable All to enable all the Action sequence in the Editor. l Select Enable to Enable a particular Action sequence and its subsequences. l Select Disable to disable a particular Action sequence and its subsequences. 2. Click OK. 13.3.2 Invoke Service (Synchronous) For invoking a synchronous service when an event is triggered for a widget, use this action sequence in the Event Editor. When you launch the Invoke Service (Synchronous) window in the Event Editor, all the services that are part of the service definition file appear in the drop-down list. Copyright © 2012 Kony, Inc. All rights reserved. Page 369 of 785 Working with Event Editor Kony Studio User Guide - 2.1 When you make a service call, you have the option to make a secure call (https call). You also have the option to block the UI till the service call is complete. Selecting this option blocks the UI and prevents you from performing other actions on the UI. Block UI Freezes the UI till the service call is complete. Secure Makes the service call through a secure connection, i.e., https protocol. Note: Block UI and Secure are mutually exclusive options You can select either of the options, both the options, or none of the options based on your requirement. Note: Kony Studio provides you with an option to mark all the service calls as Secure or UnSecure. Rightclick the application in the Applications View and select Make all service calls -> Secure/UnSecure. This option defines the mode (secure or unsecure) in which all the services in the Event Editor are invoked. Open Mapping Editor This button is enabled when you select a service. The Mapping Editor enables you to map the service parameters to the widgets on the form from which the service was invoked. Add Custom Http Headers You can add your own custom Http headers in this frame. You can define any information you want to pass in the header of the service call, apart from the default header parameters. Each row allows you to add a custom header parameter along with its value. You can define the value in the Mapping Editor or write an expression to derive the value. The header name must be unique for every custom header. You can give any name to the custom headers you define except for the reserved header names. However, it is recommended to use userfriendly names for the headers. Note: Authorization is a reserved header name that captures the user authentication details. Copyright © 2012 Kony, Inc. All rights reserved. Page 370 of 785 Kony Studio User Guide - 2.1 Working with Event Editor To define an action sequence for invoking a synchronous service, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select 3. Select a service from the drop-down list or click below: . to open Select Service window as shown i. Select a service from the list available. ii. When you type few letters of a service under Search, all the service names that begin with the characters entered are listed. iii. Select a service from the list and click OK. iv. For a selected service, you can also define custom http headers and define the corresponding values for each header. v. In the HTTP Config parameters field, specify the timeout in seconds for a network call. 4. Click Open Mapping Editor. The Mapping Editor opens. 5. Map the service parameters to variables, data store keys, or widgets on the form from which the service was invoked. 6. Click Finish on the Mapping Editor. An action sequence is defined for invoking a synchronous service. Copyright © 2012 Kony, Inc. All rights reserved. Page 371 of 785 Working with Event Editor Kony Studio User Guide - 2.1 13.3.3 Invoke Service (Asynchronous) For invoking an asynchronous service when an event is triggered for a widget, use this action sequence in the Event Editor. When you launch the Invoke Service (Asynchronous) window in the Event Editor, all the services that are part of the service definition file appear in the drop-down list. When you make a service call, you have the option to make a secure call (https call). Secure Makes the service call through a secure connection, i.e., https protocol. Note: Kony Studio provides you with an option to mark all the service calls as Secure or UnSecure. Right-click the application in the Applications View and navigate and select Utilities > Change/Replace property > Make All Services Calls > Secure/UnSecure. This option defines the mode (secure or unsecure) in which all the services in the Event Editor are invoked. Open Mapping Editor This button is enabled when you select a service. The Mapping Editor enables you to map the service parameters to the widgets on the form from which the service was invoked. Add Custom Http Headers You can add your own custom Http headers in this frame. You can define any information you want to pass in the header of the service call, apart from the default header parameters. Each row allows you to add a custom header parameter along with its value. You can define the value in the Mapping Editor or write an expression to derive the value. The header name must be unique for every custom header. You can give any name to the custom headers you define except for the reserved header names. However, it is recommended to use userfriendly names for the headers. Note: Authorization is a reserved header name that captures the user authentication details. Copyright © 2012 Kony, Inc. All rights reserved. Page 372 of 785 Kony Studio User Guide - 2.1 Working with Event Editor To define an action sequence for invoking an asynchronous service, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select 3. Select a service from the drop-down list or click below: . to open Select Service window as shown i. Select a service from the list available. ii. When you type few letters of a service under Search, all the service names that begin with the characters entered are listed. iii. Select a service from the list and click OK. iv. For a selected service, you can also define custom http headers and define the corresponding values for the header. v. In the HTTP Config parameters field, specify the timeout in seconds for a network call. 4. Click Open Mapping Editor. The Mapping Editor opens. 5. Map the service parameters to variables, data store keys, or widgets on the form from which the service was invoked. 6. Expand the Asynchronous Service node on the left frame. 7. Right-click callback sequence and define an appropriate Action Sequence for the callback sequence. 8. Click Finish on the Mapping Editor. An action sequence is defined for invoking an asynchronous service. Copyright © 2012 Kony, Inc. All rights reserved. Page 373 of 785 Kony Studio User Guide - 2.1 Working with Event Editor 13.3.4 Navigate to a Form/Popup When you want to navigate to another form when an event is triggered for a widget, use this action sequence in the Event Editor. All the forms defined within the application appear under the drop-down list when you launch the Form/Popup Navigation window. Note: This action sequence is not applicable for form - preshow event. To define an action sequence for navigating to a form, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select 3. Select a form from the drop-down list or click below: . to open Select Form/Popup window as shown Copyright © 2012 Kony, Inc. All rights reserved. Page 374 of 785 Kony Studio User Guide - 2.1 Working with Event Editor i. Select a form from the list available. ii. When you type few letters of a form under Search, all the form names that begin with the characters entered are listed. iii. Select General under Platform for all the forms to be listed. Note: If you select a specific platform under Platform, the forms that were forked for that platform appear in the list. iv. Select a form from the list and click OK. 4. Click Open Mapping Editor. The Mapping Editor opens. 5. Map the widgets in the source form to variables, data store keys, or widgets on the form from which the form was invoked. 6. Click Finish on the Mapping Editor. An action sequence is defined for navigating to a form. 13.3.5 Add Mapping When you want to map widget data within the same form upon triggering of an event for a widget, use this action sequence in the Event Editor. To define an action sequence for mapping widget data within the same form, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select . 3. Click Open Mapping Editor. The Mapping Editor opens. 4. Map the widget data to other widgets within the same form. 5. Click Finish on the Mapping Editor. An action sequence is defined for mapping widget data within the same form. 13.3.6 Show Alert Alert represents a message that is displayed to the user. When you want an alert to be displayed upon triggering of an event for a widget, use this action sequence in the Event Editor. Alerts have a specific behavior on Mobile Web. For more information, see Mobile Web Behavior. Alerts can be of three types: l Error An error message is displayed on the screen. l Information An informative message is displayed on the screen. This message can be in turn a warning or a success message. Copyright © 2012 Kony, Inc. All rights reserved. Page 375 of 785 Kony Studio User Guide - 2.1 Working with Event Editor l Confirmation A confirmation message with Yes and No options is displayed on the screen. All the alerts are modal in nature, i.e., the user cannot proceed with other UI operations unless the alert is dismissed. Note: Do not use Show Alert multiple times in the same action sequence as it could lead to erroneous behavior of the application. Note: As a best practice, alert should be the last call in any function. To define an action sequence for showing an alert, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select below. . Define Alert window appears as shown 3. Select the type of alert from the Type drop-down list. Copyright © 2012 Kony, Inc. All rights reserved. Page 376 of 785 Working with Event Editor Kony Studio User Guide - 2.1 4. Select either constant or expression from Message Type. Note: Constant indicates that the message you enter is displayed. Expression indicates that the display message is formed out of an expression. For more information about building an expression, see Working with Expression Editor. 5. Enter a message for the constant type message under #Message:. 6. Enter a title for the alert message under Title:. Note: This title is not applicable on Mobile Web and Native BlackBerry Playbook platforms. On Mobile Web, the title of the alert is provided by the browser on which the application is running. 7. Enter a value for the OK Label. For example, Yes. Note: The OK Label is not applicable on Native BlackBerry Playbook platform. 8. Select the Alignment of the alert and also the custom Icon for the alert. These properties are applicable only on Android platform. 9. Go to Internationalization tab and select the appropriate i18n Keys for the Message, Title, and OK Label. You can ignore these details if you do not wish to internationalize the alert. 10. Click OK. An action sequence for showing an alert is defined. Note: You can also display alerts programmatically. To display alerts from the code, use window.Alert API. For more information this API, see Kony API Reference Guide. 13.3.6.1 Mobile Web Behavior for Alerts Alerts have a different behavior on Mobile Web. l l l For advanced Mobile Web devices like iPhone, Android, and Palm Pre, alerts are displayed as popups. For basic devices, the alerts are displayed at the top of the form immediately after the header section. Titles of the alerts are provided by the browser and you cannot modify them. The alert title attribute does not apply for Mobile Web. Usually, the title on the alert will be the IP address or the domain name of the application. Confirmation alerts in the basic devices will be displayed in another form. On other Mobile Web platforms, it will be shown as a popup with Yes or No buttons. 13.3.7 Add Preprocess Decision When you want to execute a code snippet based on the platform on which the application is running, use this action sequence in the Event Editor. You can specify this action sequence to be executed when an event is triggered for a widget. To define an action sequence based on the platform, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 377 of 785 Kony Studio User Guide - 2.1 Working with Event Editor 1. Open Event Editor. 2. Right-click Action Sequence and select appears . Select Platform window 3. Select the required platforms. 4. Expand Preprocess Decision. 5. Right-click true and define the required action sequence. 13.3.8 Add Decision When you want to execute a code snippet or an action sequence based on a condition upon triggering of an event for a widget, use this action sequence in the Event Editor. To define an action sequence based on a condition, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select . 3. Define or build an expression. 4. Expand Decision. 5. Right-click true and define the required action sequence. Here, true is a an if condition. Note: You can also add an Else if condition in a Decision and specify an action sequence to execute if the condition evaluates to true. 6. To add an Else if condition, right-click Decision in the Action Sequence and select Else if. 7. For the condition, define or build an expression. 8. Right-click false and define the required action sequence. false is an else condition. An action sequence is defined for a decision. 13.3.9 Add Snippet When you want to execute some piece of code without defining a function in the code module, use this action sequence in the Event Editor. For a Lua application, define the snippet in the Lua tab. For a JavaScript application, define the Snippet in the JavaScript tab. To define an action sequence for adding a snippet, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select . 3. Define or build an expression or write a few lines of code that you want to be executed. Copyright © 2012 Kony, Inc. All rights reserved. Page 378 of 785 Working with Event Editor Kony Studio User Guide - 2.1 13.3.10 Invoke Function When you want to invoke a Lua function upon triggering of an event for a widget, use this action sequence in the Event Editor. Important: Ensure that you are using 3.2 Intellisense plug-ins for the newly added functions to appear in the Event Editor. To define an action sequence for invoking a function, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select appears as shown below: . User Defined Functions window 3. Select a function from the drop-down list or click to open Select Function window. In this window you can enter the first few characters of the function to search it. The input parameters for the selected function appear under the Input Params tab as shown above. The function definition along with its code appears under Function tab. Note: If you do not see the user-defined functions under the Select Function drop-down list, move all the modules from the modules folder to lua/js folder under the application in Navigator View. 4. Click Goto function is editor to open the code editor. Here you can modify the function if required. Note: Clicking this link will close the Event Editor without any warning if you have enabled Close event editor without warning in Kony Studio Preferences window. Copyright © 2012 Kony, Inc. All rights reserved. Page 379 of 785 Working with Event Editor Kony Studio User Guide - 2.1 13.3.11 Invoke Sequence When you want to invoke an action sequence that has been marked as a Global Action Sequence, you use the Invoke Sequence item. To invoke a sequence, follow these steps: 1. Open Event Editor. 2. Select Mark sequence as global if you want the action sequence to be available across the application. 3. Enter a name for the global action sequence. 4. Right-click Action Sequence and select window appears as shown below: . The Invoke Global Sequence 5. Select Use as global if you want to use the action sequence as is. This is the default selection. i. Select a global action sequence from the drop-down list. You can also search for the global sequence by entering the first few characters. ii. The Input parameters that correspond to the selected global action sequence appear in the table along with their values. Copyright © 2012 Kony, Inc. All rights reserved. Page 380 of 785 Working with Event Editor Kony Studio User Guide - 2.1 6. Select Use as local if you want to copy the action sequence to this widget, and then use it. Such an action sequence will not be global. Note: When you select Use as local on a Global Action Sequence, the action sequence is tied to the widget on which the action sequence is invoked. 13.3.12 Add Comment When you want to add a comment in between the action sequence, use this option in Event Editor. A comment is a piece of text that is either an indication or a message. Note: Comments are excluded when the code is executed. To add a comment in between the action sequence, follow these steps: 1. Open Event Editor. 2. Place the cursor in between the action sequences where you want to add a comment. 3. Right-click Action Sequence and select shown below: . Enter Comment window appears as 4. Type a comment in this window. An action sequence for adding a comment is defined. 13.3.13 Add Local Variable When you want to declare or add local variables, whose scope is limited to the action sequence you are defining, you can use this action sequence in the Event Editor. Local variables are of two types: Simple A normal variable. You can assign data to this variable Collection This is a data set that has multiple records. You can add as many columns as you want to a collection and then add data to them. Copyright © 2012 Kony, Inc. All rights reserved. Page 381 of 785 Kony Studio User Guide - 2.1 Working with Event Editor Note: Local variables are available only from the point they are declared in the action sequence. For a variable to be available throughout the action sequence, application, across forms, and services, you should add a global variable. For more information about adding global variables, see Adding Global Variables and Data Store Keys. To add a local variable in the action sequence, follow these steps: 1. Open Event Editor. 2. Right-click Action Sequence and select . 3. Select Simple to add a local variable. Local Variable window appears as shown below: i. Enter a name for the local variable under Name: and click OK. Define Variable window appears as shown below: ii. Select either constant or expression from Value Type:. Note: Constant indicates that the local variable is a constant, that is, you can specify a value for the variable. The value you enter in Value: is treated as the default value. The default value is taken into consideration if no other value is assigned to the variable at later point of time in the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 382 of 785 Working with Event Editor Kony Studio User Guide - 2.1 Note: Expression indicates that the variable value can be evaluated from an expression. The expression you build appears under Value:. For more information about building an expression, see Working with Expression Editor. iii. Select a Data Type for the local variable. The Data Type can be string, boolean, or number. Note: If the data type is boolean, you need to select a default value as true or false. For other data types, you need to specify a default value under Value:. 4. Select Collection to add a local collection. Add Local Variable window appears as shown below: i. Enter a name for the local collection and click OK. Variable Data window appears as shown below: ii. Right-click the collection name and select Add Column -> Simple to add columns to the collection. Add Variable window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 383 of 785 Working with Event Editor Kony Studio User Guide - 2.1 a. Enter a name for the column and select its data type. b. Click OK. iii. Right-click the collection name and select Add Column -> Collection to add a collection. Add Variable window appears as shown below: a. Enter a name for the collection and click OK. iv. Click Data tab. All the columns added in step ii above appear in this window. v. Click to add a new record under the columns. Click under each column to add values to those columns. vi. To set a value for each row in the column, select the row and click . The Expression Editor appears. For more information about building an expression, see Working with Expression Editor. vii. Repeat the above step to add as many records as you want. Note: If you have a collection within a collection, you can add data only till the second level from the IDE. You can set data for further levels of collection from the code modules. 13.4 Event Flow Editor The Event Flow Editor allows you to visually represent the application flow and action sequences associated with various widgets. This editor also depicts the communication between different objects in the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 384 of 785 Working with Event Editor Kony Studio User Guide - 2.1 You can use the Event Flow Editor in the same way as you use the traditional Event Editor. Unlike the traditional Event Editor, you can drag-and-drop nodes to create action sequences in the Event Flow Editor. Hence, defining action sequences in the Event Flow Editor is easy. The Event Flow Editor can be invoked to define events for the following: l l Form/Popup o transactionaldataload. o masterdataload. o preshow. o postshow. o onhide. Widgets (on which events can be defined) o HBox, TabPane, VBox. o Button, CheckBoxGroup, ComboBox, DataGrid, Image, Link, ListBox, MenuItem, RadioButtonGroup, RichText, Slider, TextBox. o Browser, Camera, HzImageStrip, ImageGallery, Map, Segment, Switch, PickerView. 13.4.1 Prerequisites Ensure that you are using: l JDK 1.6.0_20 and above. l Eclipse 3.4.2 and above. 13.4.2 Advantages The following are the advantages of representing action sequences visually within an application: l Facilitates easy review of the business flow. l Helps the developers to easily design the application logic with minimal coding. l Reduces dependencies on various programming languages as the action sequences defined here can run on any platform. 13.4.3 Capabilities The Event Flow Editor has the following capabilities: l l Allows you to: o Define and modify action sequences without programming, using a simple GUI tool. o Drag-and-drop nodes from the Palette to create action sequences. Represents the action sequences at a high-level. You can drill down into the details by opening a particular node. Copyright © 2012 Kony, Inc. All rights reserved. Page 385 of 785 Working with Event Editor Kony Studio User Guide - 2.1 l Supports copy/paste of action sequences from one widget to another widget. l Hierarchical representation of the application flow. 13.4.4 Launching the Event Flow Editor You can launch the Event Flow Editor in two ways: l l Double-click the widget that has events associated with it. Right-click the widget (that has events associated with it) and select Event Flow and the event (for which you want to define the action sequence) from the context menu. Note: If a widget has multiple events, you must select the event for which you want to launch the Event Flow Editor. Important: If an action sequence is already defined for the selected event of the widget, the Event Flow Editor displays that action sequence. 13.4.5 Palette Appearance The Palette in the Event Flow Editor lists all the nodes that can be used while defining action sequences for widgets. Copyright © 2012 Kony, Inc. All rights reserved. Page 386 of 785 Working with Event Editor Kony Studio User Guide - 2.1 You can change the appearance of the Palette as follows: l Show/Hide Palette (the Palette is displayed by default) Click l l l and on the Palette respectively to hide/show the Palette. Resize Use the mouse to resize the Palette. Dock the Palette to Left or Right (it is displayed to the right by default) Right-click the title of Palette and select Dock On -> Left or Dock On -> Right to adjust the alignment of the Palette. Layout Right-click on the Events title bar to change the Layout of the Palette. Copyright © 2012 Kony, Inc. All rights reserved. Page 387 of 785 Working with Event Editor o Columns - displays all the nodes as columns o List - displays all the nodes in a list format o Icons - displays icons of all the nodes Kony Studio User Guide - 2.1 Copyright © 2012 Kony, Inc. All rights reserved. Page 388 of 785 Working with Event Editor o Kony Studio User Guide - 2.1 Details - displays the icons of the nodes along with the details (default layout) 13.4.6 Using the Event Flow Editor To use the Event Flow Editor for defining action sequence on a particular widget, follow these steps: 1. Go to Applications View. 2. Select an application and expand the forms in it. 3. Open the required form. 4. Launch the Event Flow Editor. 5. Drag-and-drop the required nodes from the Palette on to the editor. For more information about each node in the Palette, see Action Sequences. Alternatively, you can right-click and select Add -> <the required action sequence>. 6. Right-click a specific node and select Insert Before or Insert After to add the action item at an appropriate position. Copyright © 2012 Kony, Inc. All rights reserved. Page 389 of 785 Working with Event Editor Kony Studio User Guide - 2.1 Note: Right-click any node and select Properties to open that node in the traditional Event editor. Note: You can navigate to the form from which you have launched the Event Flow Editor by clicking Back button at the top. You can also refresh the Event flow Editor if the changes you make are not visible instantly. 7. When you hover on any node, Kony Studio displays a tool tip that gives a brief description about that node. As the tooltip displays all the details about the node you do not have to double-click the node to see the details. Copyright © 2012 Kony, Inc. All rights reserved. Page 390 of 785 Kony Studio User Guide - 2.1 Working with Event Editor 8. The nodes are connected to each other in the order of creation. You can expand or collapse a node if it has more elements associated with it. For example, a Decision can be expanded or collapsed as it has true and false conditions embedded within the decision. Expanded Form Collapsed Form By default, the node is displayed in an expanded form. You can collapse it if required. Note: You can expand/collapse a Decision, Alert, or a PreprocessDecision. 9. Double-click the required node to add details for it. For example, if you have created a node to invoke a function, double-click that node and select the function that needs to be invoked. 10. Repeat the above step for each of the nodes in the action sequence. 11. Save the action sequence. An action sequence is defined on the specified widget for the specified event. 12. If you want to make the action sequence global, double-click Event Flow Editor. available in the top-left corner of the Copyright © 2012 Kony, Inc. All rights reserved. Page 391 of 785 Working with Event Editor Kony Studio User Guide - 2.1 i. Select Make sequence as global. ii. Enter a name in the Sequence Name field. iii. Click OK. When you make an action sequence as global, the entire event flow is replaced with the global action sequence. Note: A Global Action Sequence is not tied to any widget, it is independent of the widgets. Note: You can edit the global action sequence in a separate window (editor). 13. You can also print the event flow by selecting Print in the context menu of any node. 13.4.7 Hierarchical Representation of the Action Sequence You can see the action sequence defined on a particular widget in a hierarchical view or a tree view. The Outline View of Kony Studio displays a tree view of the action sequence when it is opened in the Event Flow Editor as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 392 of 785 Kony Studio User Guide - 2.1 Working with Event Editor 13.4.8 Other Actions In the Event Flow Editor, you can perform the following actions apart from defining the action sequences: Copy/Paste Allows you to copy/paste the selected node (s) or the entire action sequence to other widgets, reducing the development time. Use or on the palette to select a part or the entire action sequence. Delete Allows you to delete the selected node (s) or the entire action sequence. Zoom In Allows you to magnify the action sequence for a better view. You can also use Ctrl = (hold the Ctrl key and press the = key). Zoom Out Allows you to shrink the action sequence. You can also use Ctrl - (hold the Ctrl key and press - key). 13.5 Working with Mapping Editor The objective of Mapping Editor is to map data across widgets and service parameters. This mapping of data reduces the effort of writing code. Copyright © 2012 Kony, Inc. All rights reserved. Page 393 of 785 Working with Event Editor Kony Studio User Guide - 2.1 Mapping Editor is made up of two major parts: l Source The source appears on the left hand side of the mapping editor window as shown in the above window. The Source consists of the following: o Global Variables o Data Store Keys o i18n Keys Note: i18n Keys appear only in the source because you cannot assign any value to them once they are defined. l o Skins o Form from which the mapping editor was invoked o All the widgets on this form. Target The target appears on the right hand side of the mapping editor window as shown in the above window. Target consists of the following components: o Global Variables o Data Store Keys o Service you are invoking Copyright © 2012 Kony, Inc. All rights reserved. Page 394 of 785 Working with Event Editor o Form to which you are navigating o All the widgets on this form. Kony Studio User Guide - 2.1 13.5.1 Filter By and Search Functionality The elements under Source and Target in the Mapping Editor can be sorted by two ways: l Filter By l l l l l l l All displays all the elements i18n displays only the i18n keys skin displays only the skins By Widget Id displays widgets sorted by their ID By Widget Category displays widgets sorted by their categories variables displays only variables - local and global variables Search displays the elements that match the search string Copyright © 2012 Kony, Inc. All rights reserved. Page 395 of 785 Working with Event Editor Kony Studio User Guide - 2.1 13.5.2 Adding a form or a template to the tree You can use the Add a form/ template to the tree button to add additional entities to the Source or Target in the Mapping Editor. You can add the following categories to the Source or Target in the Mapping Editor: l forms l popups l headers l footers To add a category to the source or target of the Mapping Editor: 1. Click the Add form/template to tree button. The Add form/popup/header/footer dialog appears. 2. Select a desired category from the Category drop-down list. 3. Once a category is selected, the Select resource field is populated. l l l l If you select the category as form, the Select resource field lists all the forms defined within the application. If a single form exists in the application, the Select resource field lists None as the available option. If you select the category as popup, the Select resource field lists all the popups defined within the application. If a single popup exists in the application, the Select resource field lists None as the available option. If you select the category as header, the Select resource field lists all the headers defined within the application. If a single header exists in the application, the Select resource field lists Skin_Defaults as the available option. The Skin_Defaults option is the default skin of the header. If you select the category as footer, the Select resource field lists all the footers defined within the application. If a single footer exists in the application, the Select resource field lists Skin_ defaults as the available option. The Skin_Defaults is the default skin of the footer. 4. Click OK. 5. The additional categories added are reflected in the Mapping Editor. 13.5.3 Launching Mapping Editor Mapping Editor is invoked in case of the following action items in the Event Editor: l Invoking a service (Synchronous or Asynchronous) The form from which the service is invoked becomes the source, and the invoked service is the target. l Navigating to another form The form or service from which you are navigating is the source, and the form to which you are navigating is the target. Copyright © 2012 Kony, Inc. All rights reserved. Page 396 of 785 Working with Event Editor l Kony Studio User Guide - 2.1 Mapping within the same form The source and target is the same form in this case. 13.5.4 Important Considerations while Mapping While mapping data from source to target, you must be aware of the following: l l l l l l Data type of the source and target should be the same. When you map a collection to another collection, you must first map at the parent-level (map one collection to the other collection) and then map the elements. Source and the Target cannot be same. Tabs are listed under form elements. Hence, you cannot map any data to a tab widget using the Mapping editor. For service mappings, do not use structures that have more than simple key value pairs and attributes. Break out complex structures and use code to get the lost values. Kony service mappings can not support dynamic associations or hierarchical structures. Use code to work around this limitation Note: The Mapping Editor supports one-to-many mapping, that is, you can map the same element in the source to multiple elements in the target. To perform mapping in the Mapping Editor, follow these steps: 1. Expand all components in the Source. 2. Select a source item. 3. Expand all components in the Target. 4. Select a target item. Note: The data type should be the same for source and target. The items that are mapped are highlighted in yellow as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 397 of 785 Working with Event Editor Kony Studio User Guide - 2.1 If you try to bind two items that do not meet the mapping criteria, for example a string to a number, you get an error message as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 398 of 785 Working with Event Editor Kony Studio User Guide - 2.1 5. If you want to unbind the items that you have mapped earlier, right-click the mapped item in the target and select unbind. The binding between the two items is broken. Note: When you unbind a collection, all the elements within the collection are unbound automatically. 6. Click Finish when the mapping of items is complete. 13.5.4.1 Mapping Data with the Help of Expression You can also map data to widgets or service parameters by creating an expression. When you write an expression to map the data, you can perform the required operations on the data before mapping it to the selected element. To map data with the help of an expression, follow these steps: 1. Go to Mapping Editor. 2. Select the element in the Target to which you want to map data. 3. Right-click this element and select Add Expression. Note: You can add an expression only to the elements that have a data type associated with it. These elements can be service parameters or attributes of a widget. You cannot add an expression at the widget name or service name level. Copyright © 2012 Kony, Inc. All rights reserved. Page 399 of 785 Working with Event Editor Kony Studio User Guide - 2.1 The Expression Editor appears. 4. Define the required expression and click OK. The data derived out of the expression is mapped to the selected element. 13.5.4.2 Mapping a Collection to a Widget or a Service Parameter When you want to map elements within a collection to a widget or a service parameter, the first element in the collection gets mapped to the widget by default as shown below. Copyright © 2012 Kony, Inc. All rights reserved. Page 400 of 785 Working with Event Editor Kony Studio User Guide - 2.1 Note: You have to explicitly edit the expression to modify the index of the collection that needs to be mapped. To edit the collection index value, follow these steps: 1. Go to Mapping Editor. 2. Select an element within the collection as the source by clicking it. 3. Click a widget (or service parameter) that has the same data type as the collection element. The first element within the collection gets mapped to the widget you have selected as shown in the above window. 4. Right-click the mapped widget (or service parameter) and select Edit Expression as shown in the above window. The Expression Editor appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 401 of 785 Working with Event Editor Kony Studio User Guide - 2.1 5. Delete the default index value in the expression and provide the required index value. For example, students[3]["name"] indicates that you have mapped the value at the third index of name within the students collection. 6. Click OK. 13.6 Working with Expression Editor Expression Editor is used when an expression is to be generated using two or more variables (or widget data) with the help of API calls. Expression Editor displays a list of all APIs category-wise. You can select the category and then the required APIs to build expressions. Using Expression Editor, you can assign data to variables, perform operations on strings, numbers, variables, and data store keys. You can access Expression Editor: l from the Mapping Editor l when you add a code snippet in Event Editor. You can build an expression within the following action items: l Preprocess decision l Decision l Snippet. Copyright © 2012 Kony, Inc. All rights reserved. Page 402 of 785 Kony Studio User Guide - 2.1 Working with Event Editor l Conditions (Right-click a decision and select Else-if) l Local Variables(Simple and collection) The Expression Editor is as shown below: 13.6.1 Operators The Expression Editor has various operators that signify a specific operation. The position of the cursor is very important. The operators or APIs are inserted at the position where the cursor is placed. The operators are explained below: Operator Explanation Plus operator. Performs addition. Minus operator. Performs subtraction. Multiply operator. Performs multiplication. Divide operator. Performs division. Assign operator. Assigns data to a variable, string, number, or data store key. Concatenation operator. Concatenates two strings Left brace. Right brace. Equals operator. Compares two values and returns true if they match. Greater than. Less than. Less than or equals to. Greater than or equals to. Copyright © 2012 Kony, Inc. All rights reserved. Page 403 of 785 Kony Studio User Guide - 2.1 Working with Event Editor Operator Explanation Not equal to operator. Compares two values and returns true if they do not match. Logical and operator. Logical or operator. 13.6.2 Event Object The Expression Editor has various event objects that are associated with a widget and its event. An eventobject stands for frm.widget. The table below lists the event objects for some widgets: Widget Widget Event Button Camera onsucess onfailure onclick onclick 2D/3D Chart onclick Map onselection onpinselect Browser Event Object eventobject eventobject eventobject eventobject, column_number, row_ number location eventobject, siteinfo To set a dynamic property for a button on a form, navigate to the onclick event of the button and click an Event Object, and select eventobject eventobject.skin= skin; 13.6.3 Passing Parameters While passing parameters to the APIs, you should be aware of the following: 1. When you see <<string>> , you have to delete and replace it with a relevant string. 2. When you see <<int>> , delete that and replace it with a relevant integer. 3. When you see <<table> >, delete and replace it a relevant table name. Note: If you are retrieving values from widgets, variables, data store keys, or i18n keys, then you can directly include that in the expression. If you are specifying a constant explicitly, then it should be enclosed within double quotes (""). 13.6.4 Evaluation The formed or generated expressions need to be evaluated. l Expressions built within the preprocess decision are evaluated at build time, that is, within the IDE. l Expressions built within a snippet are evaluated at build time, that is, within the IDE. Copyright © 2012 Kony, Inc. All rights reserved. Page 404 of 785 Working with Event Editor l Kony Studio User Guide - 2.1 Expressions built within the decision action item are evaluated at the actual runtime, that is, on the mobile device. Note: An expression within a decision or a preprocess decision should always evaluate a boolean value. 13.6.4.1 Sample Expressions A few sample expressions are given below: Expression to concatenate two strings To concatenate the text of button1 button to the text of button2 button on frmPage2 form, press [Ctrl+Space] and add the widgets and properties using content assist.. Note: When you build an expression with the help of operators and APIs, click Compile to check if the built expression is syntactically correct. Copyright © 2012 Kony, Inc. All rights reserved. Page 405 of 785 Working with Services Kony Studio User Guide - 2.1 14. Working with Services A Service is an application component that represents the application's interaction with the external service data source. A service definition comprises the metadata or the configurations required to exchange data with the external data source. For example, the configurations can be - service type, service ID, input parameters, output parameters, pre and post processors, target URL, authentication credentials if required and type (HTTP/HTTPS). Service Definition enables the application to execute transactions or exchange data with any external data source. The IDE provides an out-of-box support for connecting to a Web Service and an XML Service. In case the external data source does not expose the services to these well known interfaces, the developer can build a Java service. You can define the services for the following connectors: l XML over HTTP. l Simple Object Access Protocol (SOAP). l Java - Custom connector for any other data source. l Composite - A combination of the above. Note: Kony Studio provides you with an option to mark all the service calls as Secure or UnSecure. Rightclick the application in the Applications View and select Make all service calls -> Secure/UnSecure. This option defines the mode (secure or unsecure) in which all the services in the Event Editor are invoked. 14.1 Service Definition File The Kony Application Server provides data connector support using standard interfaces such as SOAP or XML to the external data sources. The server requires a Service Definition file that defines the external data source and the data to be extracted. Each application that is hosted on the server must have a Service Definition file specific to that application. Copyright © 2012 Kony, Inc. All rights reserved. Page 406 of 785 Kony Studio User Guide - 2.1 Working with Services Each service defines the target URL, input parameters, output parameters, pre and post processors, authentication credentials if required, type (HTTP/HTTPS), etc. A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. The individual information about each service is present in <service_id>.split files in the split_services folder. The Service Definition File for different types of services is stored at the following location when it is generated: Type of Service Web Services XML Services Java Services Composite Services Location on the computer <Drive>:\<Eclipse workspace>\<AppName>\services\webservicesoap\servicedef.xml <Drive>:\<Eclipse workspace>\<AppName>\services\xml\ servicedef.xml <Drive>:\<Eclipse workspace>\<AppName>\services\java\ servicedef.xml <Drive>:\<Eclipse workspace>\<AppName>\services\composite\ servicedef.xml 14.2 Service Definition Tool Kony Studio provides a Service Definition Tool that can load WSDL URLs or add XML services and define the input/output parameters. After defining the services and deploying the Service Definition, the IDE allows you to directly map UI widgets to the parameters in a Service Definition. More complex data handling is accomplished through linking pre and post processing steps to the data service call. In case the external data source does not expose a standard API, the tool provides the ability to develop or deploy a custom Java connector. The Java connector is a class that implements the com.konylabs.middleware.common.JavaService interface. When you define services that fetch response from the external data sources, the following processes run at the back-end. These processes are handled by the Kony Application Server: l l l l Service Handler - Channelizes the request and checks if the initiated service is available in the Service Definition file. Preprocessor (Optional) - Formats the inputs that need to be passed to a service call. Data Connector - XML/SOAP/Java component that is used to connect to the external data source and fetch the desired response. Post Processor (Optional) - Formats the information that is passed back to the mobile device as a response to the service call. Copyright © 2012 Kony, Inc. All rights reserved. Page 407 of 785 Working with Services Kony Studio User Guide - 2.1 14.3 Using the Services The following are the steps involved in using any services within an application in Kony Studio: 1. Define and configure the services that use different types of data connectors: l SOAP. l XML. l Java. l SAP l Combination of any of these services. 2. Configure the services to use Preprocessor or Postprocessor (optional). 3. Test the services by invoking them within Kony Studio. l l For Web service/XML service, use the Get Response button in the Service Definition Editor to test the service call. For Java service, use the Test button in the Service Definition Editor to test the result. Note: You cannot test the services on J2ME Emulator if the service is a secure (https) service call. This is due to a SSL Certificate Issue on the J2ME platform. 4. Generate the Service Definition File based on the configurations. 5. Map the service parameters to the data elements in the application. 6. Publish the Service Definition File. 7. Build the Application. 8. Test the Output. 14.4 Preprocessor and Postprocessor Preprocessor is a component that is invoked before passing the data to the external data source. This enables the developer to include any business logic on the data before forwarding the request to the external data source. Postprocessor is a component invoked after the data is received from the external data source but before that data is returned to the mobile device. This enables the developer to include any business logic on the data before sending the response to the mobile device. The logic, in both cases, may include formatting the data elements, removing the data elements or logging the data elements (for diagnostics purposes). Preprocessor and post processor are custom Java classes. These Java classes implement the com.konylabs.middleware.common.DataPreProcessor and com.konylabs.middleware.common.DataPostProcessor Java interfaces respectively. You need to implement and load these libraries before using them. Copyright © 2012 Kony, Inc. All rights reserved. Page 408 of 785 Working with Services Kony Studio User Guide - 2.1 Preprocessor/Post processor performs the following tasks on the data that is passed to a service, or data that is retrieved from a service call, if required: l filters the data. l changes the format of the data. l adds or deletes data. If you have a preprocessor defined in a service call, the preprocessor library is invoked first before making the service call. The IDE provides an option to browse and select the pre-processor or post-processor libraries in the Service Definition Editor for all the types of services. Note: Invoking a preprocessor or a post processor within any type of service is optional. The need to invoke these libraries depends on your requirement. Important: The preprocessor or postprocessor name must start with com.kony or com.konylabs . 14.4.1 Best Practices The following are the best practices that relate to pre-processors or post-processors: l Use log4j statements instead of System.out.println() statements. l Wrap the debug statements with log.isDebugEnabled() method. For example, if (logger.isDebugEnabled()) { ...logger.debug("printing debug info") } 14.4.2 Sample Preprocessor The following is a sample preprocessor file: import java.util.HashMap; import org.apache.log4j.Logger; import com.konylabs.middleware.common.DataPreProcessor; import com.konylabs.middleware.controller.DataControllerRequest; import com.konylabs.middleware.dataobject.Result; import com.konylabs.middleware.session.Session; public class TestPreProcessor implements DataPreProcessor { ...public boolean execute(HashMap hm, DataControllerRequest dcRequest, Result result) throws Exception ...{ .........//Write application logic here Copyright © 2012 Kony, Inc. All rights reserved. Page 409 of 785 Working with Services Kony Studio User Guide - 2.1 .........// if true is returned then service call and post processor are invoked. If false is returned, then service call and post processor are not invoked. ......return true ...} } 14.4.3 Sample Post Processor The following is a sample postprocessor file: import java.util.ArrayList; import org.apache.log4j.Logger; import com.konylabs.middleware.common.DataPostProcessor; import com.konylabs.middleware.controller.DataControllerRequest; import com.konylabs.middleware.dataobject.Param; import com.konylabs.middleware.dataobject.Result; public class TestPostProcessor implements DataPostProcessor { ...public Object execute(Result results, DataControllerRequest dcRequest) ...{ ......//Write application logic here to modify the results returned from the service ...... ......// return Result object here ...return results; ...} } 14.5 Data Provider The DataProvider interface allows the users to provide custom implementation for connection establishment to a third party service and to generate a response. Using this , users use the existing components which form the request metadata by reading service definition and parse the response as per the service definition. The DataProvider.execute() method is implemented such that after the execution, the DataControllerResponse object should be populated with response, characterEncoding, and status code. 14.5.1 Sample Data Provider The following is a sample data provider file: import java.io.File; import java.util.HashMap; Copyright © 2012 Kony, Inc. All rights reserved. Page 410 of 785 Working with Services Kony Studio User Guide - 2.1 import java.util.List; import java.util.Map; import com.konylabs.middleware.common.DataProvider; import com.konylabs.middleware.controller.DataControllerRequest; import com.konylabs.middleware.controller.DataControllerResponse; import com.konylabs.middleware.exceptions.ConnectorException; public class SampleDataProvider implements DataProvider{ @Override public void execute(String arg0, DataControllerRequest arg1, DataControllerResponse DCresponse, String arg3, Map<String, String> arg4, List<File> arg5, HashMap arg6) throws ConnectorException { System.out.println(":::::::entered:::SAMPLE DATAPROVIDER:"); System.out.println(":::::::DataController Request::::"+arg1.toString ()); System.out.println(":::::::DataController Request::::"+arg0.toString ()); //System.out.println(":::::::DataController Request::::"+arg3.toString()); //Respose generation String xmlResult = "" + "<soap:Envelope xmlns:soap=\"http://schemas.xmlsoap.org/soap/envelope/\">"+ "<soap:Body>"+ "<AllPlayerNamesResponse xmlns:m=\"http://footballpool.dataaccess.eu\">"+ "<AllPlayerNamesResult>"+ "<tPlayerNames>"+ "<iId>1434</iId>"+ "<sName>Lucas Barrios</sName>"+ "<sCountryName>Winner SF-II</sCountryName>"+ "<sCountryFlag>http://footballpool.dataaccess.eu/images/flags/ </sCountryFlag>"+ "</tPlayerNames>"+ "<tPlayerNames>"+ "<iId>715</iId>"+ "<sName>Alexander Frei</sName>"+ "<sCountryName>Winner SF-II</sCountryName>"+ "<sCountryFlag>http://footballpool.dataaccess.eu/images/flags/ </sCountryFlag>"+ "</tPlayerNames>"+ Copyright © 2012 Kony, Inc. All rights reserved. Page 411 of 785 Kony Studio User Guide - 2.1 Working with Services "</AllPlayerNamesResult>"+ "</AllPlayerNamesResponse>"+ "</soap:Body>"+ "</soap:Envelope>"; //Data Response setting DCresponse.setResponse(xmlResult); DCresponse.setCharsetEncoding("UTF-8"); DCresponse.setStatusCode(200); //System.out.println(":::::::DataController Request::::"+DCresponse.toString()); } } 14.6 Response Encoding Schemes The response fetched from a Web Service or an XML Service from the external data source follows a certain encoding scheme to support different languages or character sets. The response can be encoded using the following formats: Encoding Algorithm UTF-8 ISO-8859-1 US-ASCII UTF-16 UTF-16BE UTF-16LE Windows-1250 Windows-1251 Windows-1252 Windows-1253 Windows-1254 Windows-1255 Windows-1256 Windows-1257 Windows-1258 Description UCS (Unicode Code Space) Transformation Format - 8 bit. Represents every character in the Unicode character set. This is the default encoding format. Encoding scheme to support the first set of Latin alphabet, which contains 191 characters Encoding scheme based on the sequence of characters in the English alphabet 16-bit UTF encoding scheme UTF 16 bit Big Endian. Encoding scheme that maps Unicode character set to a sequence of 2 bytes (16 bits) UTF 16 bit Little Endian. Encoding scheme that maps Unicode character set to a sequence of 2 bytes (16 bits) Encoding scheme (under Microsoft Windows) for languages that use Latin script 8-bit encoding scheme for languages that use Cyrillic alphabet Encoding scheme for the Latin alphabet Encoding scheme for modern Greek language Encoding scheme for Turkish language Encoding scheme for Hebrew language Encoding scheme for Arabic language Encoding scheme for Estonian, Latvian, and Lithuanian languages under Microsoft Windows Encoding scheme for Vietnamese texts Copyright © 2012 Kony, Inc. All rights reserved. Page 412 of 785 Working with Services Kony Studio User Guide - 2.1 14.7 Input and Output Parameters Input parameters are the parameters that you pass to the service and are used during a service call. Some of the services may not have input parameters. Input parameters are used when dynamic content is passed to the external data source. Output parameters are the parameters that are fetched from the response of a service call. These are formatted as per the requirement before they are displayed on the device. The service parameters have a scope and data type attached to them. While defining the input and output parameters for a service, you need to define the scope and the data type. 14.7.1 Input Parameters The following attributes are defined for Input Parameters: 1. ID- Unique identifier for a parameter. 2. Test Value - The value to be used to test the service within the Service Definition Tool. This value is not the part of the final Service Definition file. 3. Scope - The scope can be request or session. l l request - Indicates that the value has to be retrieved from the http request received from the mobile device. session - Indicates that the value has to be retrieved from the http session stored on the Kony Application Server. 4. Datatype - Type of the data. These datatypes are defined here and are used for mapping appropriately in the Mapping editor. It can belong to the following data types: l string - Represents a combination of alpha-numeric and special characters. Supports all formats including UTF-8 and UTF-16 with no maximum size limit. l boolean - Represents a value that can be either true or false. l number - Represents an integer or a floating number. l collection - Represents a group of data, also referred to as data set. This value is received from the client as a JSON string. Important: Datatypes boolean, number, and collection are not available in Java Services. 5. Encode - True or False. Specifies if the URL needs to be encoded or not. URL encoding converts the characters into a format that can be safely transmitted over the Internet. For example, if the word New York Times is to be passed as part of the URL, it would be encoded as New%20York%20Time when the encoding is set to True adhering to the HTML URL encoding standards. 14.7.2 Output Parameters The following attributes are defined for Output Parameters: Copyright © 2012 Kony, Inc. All rights reserved. Page 413 of 785 Working with Services Kony Studio User Guide - 2.1 1. ID - Unique name that we use in our code to access this value. 2. Xpath - Xpath is applied for extracting the required elements from the response of the service call. XPath is used to navigate through elements and attributes in an XML document. For more information about XPath, see http://www.w3schools.com/xpath/. 3. Scope - The scope can be response or session. l response - Indicates that the parameter is included in the final response that is sent to the mobile device. Note: Mark only those parameters that are represented on the device UI as response scope. l session - Indicates that the parameter gets stored in the session on the Kony Application Server, that is, this parameter need not be included in the response that is sent to the mobile device. Note: It is a best practice to mark the session tokens, apart from cookies returned from the data source, as session scope. 4. Datatype - Type of the data. It can belong to the following data types: l string - Represents a combination of alpha-numeric and special characters. Supports all formats including UTF-8 and UTF-16 with no maximum size limit. l boolean - Represents a value that can be either true or false. l number - Represents an integer or a floating number. 5. Collection ID - Groups data elements under the specified parameter as a collection. Collection is created to assign grouped data to segment or a table in the UI. 6. Record ID - Groups data elements under the specified parameter as a record. Typically we use this to provide metadata to the segment. 7. Format- Can be set to None, currency, number or date. 8. Format Value - Standard for converting to the specified format. l Number - for number format refer to java.text.DecimalFormat. l Currency - for currency format refer to java.text.DecimalFormat l Date - for date format refer to java.text.SimpleDateFormat 14.8 Creating a Web (SOAP)/Sharepoint Service Use Case 1. A mobile device user uses his device to perform a routine operation of getting the city weather based on the ZIP Code. The device initiates the service request. 2. Kony Application Server runs the back-end processes. 3. The response is fetched from the service and is sent to the application. 4. Response is displayed to the user. Copyright © 2012 Kony, Inc. All rights reserved. Page 414 of 785 Working with Services Kony Studio User Guide - 2.1 To create the service definitions for an external data source providing SOAP interface, use Web Service (SOAP) Service Definition Tool. You need to have a WSDL URL/file to create the Service Definition. For this example, we will use a WSDL URL of a weather application which has a GetCityWeatherByZip service and provide appropriate configurations for the Service Definition. Note: After you provide SharePoint server IP address and port, the IDE loads all the WSDLs exposed by SharePoint server. You can browse the WSDLs and their services associated with it. Users can view the WSDL service input and output parameters in the Web Service Definition Files. Input and Output parameters can be classes or primitive types. Note: If you have defined the credentials of the SharePoint server, it will show up within the Web Services folder. Expand the Web Services/SharePoint Server folder and click the service you want to add. For more information about defining SharePoint services WSDLs.. 14.8.1 Create Services from WSDL URL To create a web service, follow these steps: 1. Open Kony Studio and go to the Applications View. 2. Create an application with the name WeatherApp. For more information on creation of applications and forms, see Working with Applications section. 3. Right-click the application. A context menu appears as shown below: 4. Select Service Definition -> Web Services (SOAP). 5. The Web Service (SOAP) Definition window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 415 of 785 Working with Services Kony Studio User Guide - 2.1 6. Right-click WSDL URLS and click Add WebService WSDL to enter the URL. This is the URL that has the defined services. 7. In the WSDL Service Details window, enter the WSDL URL, the name of the WSDL service and basic credentials. 8. Click Finish. Service Definition Tool contacts the target server and loads the URL with its associated Services. 9. To add the services into the IDE, right-click on the required service and click Add. 10. The services are added to the Selected Services pane. 11. Select the service GetCityWeatherByZip from the Selected Services pane. All the input parameters and output parameters of the service are loaded and are viewable in the left pane. 12. Information associated with the GetCityWeatherByZip service is populated into the Service and Request tab of the Response/Request pane in the Service Definition Tool. Since we are not aware of the zip code that the end user provides as an input in the application, we provide a substitute parameter in the code of the request pane and provide appropriate input parameters in the Input Parameters pane. When the user provides a zip code in the application and issues a request, the zip code is substituted in the request that is sent to the external data source. In this case, we provide a substitute parameter for <weat:ZIP> ?</weat:ZIP> with <weat:ZIP>$ZIP</weat:ZIP> 13. Add Pre/Post Processors (Optional). If you need to add a preprocessor or a post processor to the request or response of the services, perform the following actions in the Pre/Postprocessor Libraries pane: i. Right-click Pre/Postprocessor libraries and select Load. ii. Browse to the folder where the required jar files and libraries are located. Copyright © 2012 Kony, Inc. All rights reserved. Page 416 of 785 Working with Services Kony Studio User Guide - 2.1 iii. Select the required jar files and libraries and click Open. All the selected jar files and libraries are loaded into the IDE and they are ready for use. 14. Data Provider Class (Optional): If you need to add a Data Provider for a service, perform the following actions: i. Right-click libraries and select Load. ii. Browse to the folder where the required jar files and libraries are located. iii. Select the required jar files and libraries and click Open. All the selected jar files and libraries are loaded into the IDE and they are ready for use. Note: Invoking a preprocessor or a post processor within any type of service is optional. The need to invoke these libraries depends on your requirement. 15. In the Service pane, enter the following information: i. Soap Action - This is auto populated from the WSDL. ii. User ID and Password - Provide this information if the external web service requires form/basic authentication. iii. Preprocessor Name - Enter the Preprocessor file name. iv. Postprocessor Name - Enter the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. v. Data Provider Name - Enter the Data Provide class name. Note: For more information on Data Provider, see the section Data Provider. vi. URL Provider - Enter the URL Provider file name. Note: URL Provider is a Java class that manipulates the URL or the parameters of the URL for the external data source. Click here to view a sample code for the URL Provider. vii. Timeout (in ms) - Specifies the maximum time (in milli seconds) the service waits for a response, before terminating the connection to the external data source. viii. Cachable - Specifies if the service response must be stored in the cache. ix. Cachable Duration - This option is enabled if you select the Cachable property. This property specifies the time duration in seconds. Note: If this service is Cachable and a call is made before the specified time duration, the service response is fetched from the Cache, else a fresh service call is made to fetch response from the server. x. In the Server Authentication field, provide the authentication details of the server from which the service will be fetched. To enable NTLM and Proxy authentication configuration, refer Appendix Proxy and NTLM Authentication Configuration. Copyright © 2012 Kony, Inc. All rights reserved. Page 417 of 785 Working with Services Kony Studio User Guide - 2.1 xi. Select appropriate Response encoding scheme. The default value is UTF-8. For more information about different encoding schemes supported by Kony Studio, see Response Encoding Schemes. 16. Add HTTP Header (Optional). Add HTTP Header if you need to add a custom http header as required by the external data source. i. Select HTTP Headers tab in the screen shown below: ii. Click Add. A row gets added to the table. iii. Enter the value for ID. iv. Enter a Test Value. Test Value is the value that is used for testing the service. This is the value that is substituted during the service call while testing the service. v. Select a value for Scope from the drop-down list. Scope denotes whether the value for the header is taken from the http request or a http session. 17. Add Input Parameters to the Service. Input parameters are the parameters that you pass to the service and are used during a service call. All the services do not have input parameters. We provide the input parameters based on the elements that are present in the Request pane. i. Select Input Parameters tab in the screen shown below: ii. Click Add. A row gets added to the table. iii. Enter the value for ID as ZIP. Copyright © 2012 Kony, Inc. All rights reserved. Page 418 of 785 Working with Services Kony Studio User Guide - 2.1 iv. Enter a Test Value. Test Value is the value of the parameter that is used for testing the service. This is the value that is substituted in place of $ZIP during a service call. Refer to Step No.10 above. To test the service let us provide the test value as 10001. v. Select a value for Scope from the drop-down list. Scope denotes the scope of the parameter, if it is limited to request or a session. vi. Select a value for Datatype from the drop-down list. Datatype denotes the type of the parameter. The datatype can also be of the type collection. For more information about mapping request and responses for a collection refer Collection. vii. Select True or False for Encode. Specifies if the URL needs to be encoded or not viii. If you need to delete a parameter row, select the parameter row you want to delete and click Delete. This action removes the parameter row from the list of service parameters. 18. Test the Service. After you configure a service, you have the option to test the service from the IDE itself. When you click Get Response in the Service pane, a service call is made with the input parameters. The service call returns data, that is, output parameters. By testing the service in the IDE, you know if the service call is fetching the data from the server as per your requirement. i. Request pane shows the request code that is passed to the URL as a service call. ii. The response fetched is shown in the Response tab. iii. Select the XML code in the window, right-click and select Format to present the code in a readable format. 19. Add Output Parameters to the Service response. We format the output parameters based on the response we get from the tested service call, which is displayed in the Response pane. i. Select Output Parameters tab in the screen shown below: ii. Click Add. A row gets added to the table. Copyright © 2012 Kony, Inc. All rights reserved. Page 419 of 785 Kony Studio User Guide - 2.1 Working with Services iii. Enter values for ID. It is advisable to create an ID that easily identifies the elements that we would like to capture from the response. iv. Apply XPath for extracting the required elements from the response of the service call. XPath is used to navigate through elements and attributes in an XML document. For more information about XPath, see http://www.w3schools.com/xpath/. In this example, we provided the XPath as follows: ID State City Temperature Humidity Wind XPath //GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult /State //GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult /City //GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult /Temperature //GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult /RelativeHumidity //GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult /Wind Note: Kony Studio supports all functions of XPath 1.0, except the translate function. v. Select a value for Scope from the drop-down list. Scope denotes the scope of the parameter, if it is limited to response or session. vi. Select a value for Datatype from the drop-down list. Datatype denotes the type of the parameter. vii. Collection ID - Groups data elements under the specified parameter as a collection. Collection is created to assign grouped data to segment or a table in the UI. viii. Record ID - Groups data elements under the specified parameter as a record. Typically we use this to provide metadata to the segment. ix. Format - Can be set to None, currency, number or date. x. Format Value - Provide the conversion standard for the selected format. xi. If you need to delete a parameter row, select the parameter row you want to delete and click Delete. This action removes the parameter row from the list of service parameters. 20. Check the result of the output parameter by clicking the Results radio button. It displays the desired element configured in the output parameter. In this example, we got the following output: Copyright © 2012 Kony, Inc. All rights reserved. Page 420 of 785 Kony Studio User Guide - 2.1 Working with Services 21. Click Save icon on the toolbar. 22. Click Generate Service Definition icon to create a Service Definition file. Note: Before generating the file, make sure all the definitions are saved and working properly. The service definition file generated is specific to Web services and appears under services in the Applications View as shown below. A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. The individual information about each service is present in <service_id>.split files in the split_services folder. The service definition file looks similar to the following: <?xml version="1.0" encoding="UTF-8" ?> ...<application id="WeatherApp" name="" desc=""> ......<services> .........<service id="GetCityWeatherByZIP" type="soapserviceConnector" cacheable="false" cacheduration=""> ............<service-config> ...............<config-param name="endpointUrl" value="http://wsf.cdyne.com/WeatherWS/Weather.asmx" /> ...............<config-param name="soapAction" value="http://wsfh.cdyne.com/WeatherWS/GetCityWeatherByZIP" /> ...............<config-param name="userid" value="" /> ...............<config-param name="pwd" value="kds/0eUc+i3BqFqSkpCk4g==" /> ...............<config-param name="postprocessorname" value="" /> ...............<config-param name="preprocessorname" value="" /> Copyright © 2012 Kony, Inc. All rights reserved. Page 421 of 785 Working with Services Kony Studio User Guide - 2.1 ...............<config-param name="urlprovider" value="" /> ...............<config-param name="proxyname" value="" /> ...............<config-param name="proxyport" value="" /> ...............<config-param name="proxyusername" value="" /> ...............<config-param name="proxypwd" value="kds/0eUc+i3BqFqSkpCk4g==" /> ............</service-config> .........<service-input> ............<template-param name="message" value="&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/ envelope/&quot; xmlns:weat=&quot;http://wsf.cdyne.com/WeatherWS/&quot;&gt;&lt; soapenv:Header/&gt;&lt;soapenv:Body&gt;&lt;weat:GetCityWeatherB yZIP&gt; &lt;!--Optional:-&gt;&lt;weat:ZIP&gt;$ZIP&lt;/weat:ZIP&gt;&lt;/weat: GetCityWeatherByZIP&gt;&lt;/soapenv:Body&gt;&lt;/soapenv:Envelo pe&gt;"> ...............<param name="ZIP" datatype="string" format="" formatvalue="" value="" src="request" target="" sms-name="" /> ............</template-param> .........</service-input> .........<service-output> ............<param name="State" datatype="string" format="" formatvalue="" targetdatatype="java.lang.String" src="//GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult/St ate" target="response" sms-name="" /> ............<param name="City" datatype="string" format="" formatvalue="" targetdatatype="java.lang.String" src="//GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult/Ci ty" target="response" sms-name="" /> ............<param name="Temperature" datatype="string" format="" formatvalue="" targetdatatype="java.lang.String" src="//GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult/Te mperature" target="response" sms-name="" /> ............<param name="Humidity" datatype="string" format="" Copyright © 2012 Kony, Inc. All rights reserved. Page 422 of 785 Working with Services Kony Studio User Guide - 2.1 formatvalue="" targetdatatype="java.lang.String" src="//GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult/ RelativeHumidity" target="response" sms-name="" /> <param name="Wind" datatype="string" format="" formatvalue="" targetdatatype="java.lang.String" src="//GetCityWeatherByZIPResponse/GetCityWeatherByZIPResult/Wi nd" target="response" sms-name="" /> .........</service-output> ......</service> .../services> </application> 14.8.2 Map the Services to the Application To map the services in the application, follow these steps: 1. In the WeatherApp application, create two forms - InputZip and OutputWeather, as shown in the images below: InputZip form - A form with a text box to take ZIP code as input and a Button. OutputWeather form - A form with Labels and Text Boxes to display the output (State, City, Temperature, Humidity and Wind). Copyright © 2012 Kony, Inc. All rights reserved. Page 423 of 785 Working with Services Kony Studio User Guide - 2.1 2. In the InputZip form, select the Button. All the properties related to the button appear in the Properties tab of the selected button. 3. In the Properties tab, scroll down to the Event section and select onclick. Click the button that appears next to Not Defined. 4. An Event Editor window appears. In the Define Action Sequence pane, Right-click on Action Sequence and select Invoke Service.Here we define the action sequence that should take place when the Button is clicked on the WeatherApp application on the device. Copyright © 2012 Kony, Inc. All rights reserved. Page 424 of 785 Working with Services Kony Studio User Guide - 2.1 Invoke Service pane appears next to Define Action Sequence pane. 5. Select the service GetCityWeatherByZip from Select Service drop down box. Click Open Mapping Editor. Mapping Editor appears. Mapping Editor allows you to map data from form widgets to the service elements. 6. Select the text:string under TextBox from the Source pane and map it to the ZIP:string under Service-GetCityWeatherByZip in the Target pane. Copyright © 2012 Kony, Inc. All rights reserved. Page 425 of 785 Working with Services Kony Studio User Guide - 2.1 Note: In the final WeatherApp application, as a result of this mapping, the value is assigned to the ZIP input parameter of the service and Kony application server invokes a service call to the external data source. The returned response from external data source is used in the next steps of the sequence. 7. Click Finish. 8. In the Define Action Sequence pane, Right-click on Action Sequence and select Navigate to Form/Popup. In this action sequence we are defining that after the service invoke call, the next sequence is to navigate to a form. Note: The goal here is to show the output of the service call in a new form. Here we select the designated form and map the service output parameters to the form elements. Copyright © 2012 Kony, Inc. All rights reserved. Page 426 of 785 Working with Services Kony Studio User Guide - 2.1 Form/Popup Navigation pane appears next to Define Action Sequence pane. 9. Select the form OutputWeather from Select Form/Popup drop down box. Click Open Mapping Editor. 10. Select each of the output parameters under Service-GetCityWeatherByZip and map them to the corresponding Text Boxes of the form, in the target pane. Copyright © 2012 Kony, Inc. All rights reserved. Page 427 of 785 Kony Studio User Guide - 2.1 Working with Services Output Parameters Service - GetCityWeatherByZip>State:string Service - GetCityWeatherByZip>City:string Service GetCityWeatherByZip>Temperature:string Service - GetCityWeatherByZip>Humidity:string Service - GetCityWeatherByZip>Wind:string Mapped to TextBox-State>Common>text:string TextBox-City>Common>text:string TextBox-Temperature>Common>text:string TextBox-Humidity>Common>text:string TextBox-Wind>Common>text:string 11. Click Finish. 12. Click OK in the Event Editor. 14.8.3 Build the Application Once the development of the application is complete, build the application. Once built, the application can be tested for its performance, published on a server, or installed on the mobile device. 1. In the Applications tab, Right-click on WeatherApp. 2. Select Build > Clean and Rebuild All. 3. In the Build Generation window, select the platforms for which you like to build the weather application. 4. Click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 428 of 785 Working with Services Kony Studio User Guide - 2.1 5. Build generation begins and the application is built. The status of the build generation and completion is displayed in the Build Generation Status window and the Console window. 14.8.4 Publish the Service Definition File Provide the appropriate Server details to publish the Service Definition File to the Server. 14.8.5 Test the Application Once the Service Definition file is published on the Kony Application Server, the application is now ready to be tested. Note: You cannot test the services on J2ME Emulator if the service is a secure (https) service call. This is due to a SSL Certificate Issue on the J2ME platform. 1. Rebuild the application. 2. Navigate to the Emulators window. The emulators are marked in green if: l the emulators are configured correctly with the installation path of the emulators and l the application is built successfully for that platform. 3. Double-click one of the emulators marked in green. Depending on the emulator you choose, you may have to navigate to the location of the application and click it. Copyright © 2012 Kony, Inc. All rights reserved. Page 429 of 785 Working with Services Kony Studio User Guide - 2.1 4. WeatherApp application start page appears on the emulator screen. 5. Enter a valid zip code in the text box and click the button next to it. Copyright © 2012 Kony, Inc. All rights reserved. Page 430 of 785 Working with Services Kony Studio User Guide - 2.1 6. Kony Application Server processes the request and displays the response on the emulator. 14.8.6 Collection You can now map collections within your SOAP request to your application. If you want your collection to be displayed for certain iterations, you can also add a for loop to your SOAP contract. IDE now supports n level nested collections as a part of the request template. An example of a single level collection is as follows: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:sap-com:document:sap:soap:functions:mc-style"> <soapenv:Header/> <soapenv:Body> <urn:ZFmmmGoodsReceiptKony> <!--Optional:--> <IGrCreate> <GRHeader> <HId>$HId</HId> <HTime>$HTime</HTime> <HUser>$HUser</HUser> Copyright © 2012 Kony, Inc. All rights reserved. Page 431 of 785 Kony Studio User Guide - 2.1 Working with Services <!--Add the for loop for Zero or more repetitions:--> #foreach $items <item> <Bldat>$Bldat</Bldat> <Budat>$Budat</Budat> <Mtsnr>$Mtsnr</Mtsnr> <Usnam>$Usnam</Usnam> <PoNumber>$PoNumber</PoNumber> <PoItem>$PoItem</PoItem> <PoUnit>$PoUnit</PoUnit> <QuantityRec>$QuantityRec</QuantityRec> <UnloadPoint>$UnloadPoint</UnloadPoint> <Xsaut>$Xsaut</Xsaut> </item> #end <!--end of loop:--> </GRHeader> </IGrCreate> </urn:ZFmmmGoodsReceiptKony> </soapenv:Body> </soapenv:Envelope> You can similarly have multiple nested collections and you can define a for loop for each of the nested collections. Ensure that each of the for loop has a unique identifier name. For example #foreach $<uniqueidentifier>. Since Kony Studio parses the items and creates a service definition template using end of line logic for each for statement till for end of loop. <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:sap-com:document:sap:soap:functions:mc-style"> <soapenv:Header/> <soapenv:Body> <urn:ZFmmmGoodsReceiptKony> <!--Optional:--> <IGrCreate> <GRHeader> <HId>$HId</HId> <HTime>$HTime</HTime> <HUser>$HUser</HUser> <!--Zero or more repetitions:--> #foreach $items <item> <Bldat>$Bldat</Bldat> <Budat>$Budat</Budat> <Serialno> <!--Zero or more repetitions:--> #foreach $SerialNo <item> Copyright © 2012 Kony, Inc. All rights reserved. Page 432 of 785 Kony Studio User Guide - 2.1 Working with Services <Gernr>$Gernr</Gernr> <UnloadPoint>$UnloadPoint</UnloadPoint> #foreach $test <XXX>$a</XXX> #end </item> #end </Serialno> </item> #end </GRHeader> </IGrCreate> </urn:ZFmmmGoodsReceiptKony> </soapenv:Body> </soapenv:Envelope> Scenario 1: If the input value for an element is not provided, you can include an exclamation mark "!" after the "$" (for example, <Bldat>$!Bldat</Bldat>) to generate a collection that includes null value. For example: <Bldat></Bldat> To avoid this empty <Bldat></Bladat> tag, you can use the following if condition statement: #if ($Bldat) <Bldat>$!Bldat</Bldat> #end Scenario 2: If a Key is missing in the input parameter, write the template in the following manner and past it in the request tab: <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:sap-com:document:sap:soap:functions:mc-style"> <soapenv:Header/> <soapenv:Body> <urn:ZFmmmGoodsReceiptKony> <!--Optional:--> <IGrCreate> <GRHeader> <HId>$HId</HId> <HTime>$HTime</HTime> <HUser>$HUser</HUser> <!--Zero or more repetitions:--> #foreach ($rec in $items.records) #set( $Budat = $rec.getParam ("Budat").getEscapeXMLValue()) #set( $Bldat = $rec.getParam ("Bldat").getEscapeXMLValue()) #set( $SerialNo = $rec.getDatasetById ("SerialNo")) <item> <Bldat>$Bldat</Bldat> Copyright © 2012 Kony, Inc. All rights reserved. Page 433 of 785 Kony Studio User Guide - 2.1 Working with Services <Budat>$Budat</Budat> <Serialno> <!--Zero or more repetitions:--> #foreach ($rec in $SerialNo.records) #set( $Gernr ("Gernr").getEscapeXMLValue()) #set( $UnloadPoint = $rec.getParam ("UnloadPoint").getEscapeXMLValue()) <item> <Gernr>$Gernr</Gernr> <UnloadPoint>$UnloadPoint</UnloadPoint> </item> #end </Serialno> </item> #end </GRHeader> </IGrCreate> </urn:ZFmmmGoodsReceiptKony> </soapenv:Body> </soapenv:Envelope> After you have structured your xml do the following: 1. Copy and paste this xml in the Request tab. 2. Click Add. A row gets added to the table. 3. Enter the value for ID. The ID should be the same as that of loop of the collection. For example if the loop is #foreach $items the corresponding ID should be items 4. Enter a Test Value. Test Value is the value of the parameter that is used for testing the service. The test value for a collection could be of the form: [{"Bldat":"123","Budat":"adf","SerialNo":[{"Gernr":"AAAA","UnloadPoint":"adadad","test":[{a:abc}, {a:def}]} ,{"Gernr":"BBBB","UnloadPoint":"adadad","test":[{a:abc},{a:def}]}]}] For an item whose value whose value is empty specify it as []. 5. Select a value for Scope from the drop-down list. Scope denotes the scope of the parameter, if it is limited to request or a session. 6. Set the value of the Datatype as collection. 7. Select True or False for Encode. Specifies if the URL needs to be encoded or not 8. If you need to delete a parameter row, select the parameter row you want to delete and click Delete. This action removes the parameter row from the list of service parameters. Copyright © 2012 Kony, Inc. All rights reserved. Page 434 of 785 Working with Services Kony Studio User Guide - 2.1 9. Navigate to the response pane and fetch the response. 10. Follow the procedure after step 19. 14.9 Creating an XML Service A service that communicates with an external data source using an XML data connector over the HTTP protocol is known as an XML Service. You must create a service definition file for the XML services. Use Case This section explains creation of an XML service for the following example: l l The user enters the latitude and longitude values on a form in the mobile application. The application invokes the designated XML service and hits the URL defined in the service with the longitude and latitude values as input parameters. l The service fetches the response and the response is sent back to the application. l The response received is displayed on a form to the user. To create an XML service, follow these steps: 1. Go to Applications view. 2. Right-click the GetStockQuotes application and select Service Definition -> XML Services. The Service Definition Editor appears. 3. Do any one of the following: a. Right-click Services and select Add. b. If you have defined an XML service in the workspace, it will show up within the Restful Services folder. Expand the Restful Services folder and click on a service you want to add. 4. In the New Service window, enter the name as getAddress and click Finish. 5. Enter the URL as http://maps.google.com/maps/geo?q=$latitude,$longitude&output=xml. For this example, we hit the Google Maps server to get the address of a place based on the latitude and longitude details. Copyright © 2012 Kony, Inc. All rights reserved. Page 435 of 785 Kony Studio User Guide - 2.1 Working with Services 6. Click Input Parameters and define the parameters for this service as follows: Parameter Test Value Data Type latitude longitude 40.751043 -73.990657 number number Note: These values are specific to the example given here. You must do the mapping between the service parameters and the form elements to capture the values that the user enters and pass them to the service. 7. Click Output Parameters and define the parameters as follows: Parameter searchresults coordinates address cntNameCode cntName XPath /kml/Response Placemark/Point/coordinates/text() Placemark/address/text() Placemark/AddressDetails/Country/ CountryNameCode/text() Placemark/AddressDetails/Country/ CountryName/text() Collection ID searchresults searchresults searchresults searchresults Note: Kony Studio supports all functions of XPath 1.0, except the translate function. 8. Enter the optional values based on your requirement. o User ID o Password o Preprocessor Name o Postprocessor Name o URL Provider o Timeout (in ms) o Cachable and Cachable Duration Copyright © 2012 Kony, Inc. All rights reserved. Page 436 of 785 Working with Services Kony Studio User Guide - 2.1 9. In the Service pane, enter the following information: i. User ID and Password - Provide this information if the external web service requires form/basic authentication. ii. Preprocessor Name - Enter the Preprocessor file name. iii. Postprocessor Name - Enter the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. iv. Data Provider Name - Enter the Data Provide class name. Note: For more information on Data Provider, see the section Data Provider v. URL Provider - Enter the URL Provider file name. Note: URL Provider is a Java class that manipulates the URL or the parameters of the URL for the external data source. Click here to view a sample code for the URL Provider. vi. Timeout (in ms) - Specifies the maximum time (in milli seconds) the service waits for a response, before terminating the connection to the external data source. vii. Cachable - Specifies if the service response must be stored in the cache. viii. Cachable Duration - This option is enabled if you select the Cachable property. This property specifies the time duration in seconds. Note: If this service is Cachable and a call is made before the specified time duration, the service response is fetched from the Cache, else a fresh service call is made to fetch response from the server. ix. In the Server Authentication field, provide the authentication details of the server from which the service will be fetched. To enable NTLM and Proxy authentication configuration, refer Appendix Proxy and NTLM Authentication Configuration. x. Select appropriate Response encoding scheme. The default value is UTF-8. For more information about different encoding schemes supported by Kony Studio, see Response Encoding Schemes. 10. Add HTTP Header (Optional). Add HTTP Header if you need to add a custom http header as required by the external data source. Copyright © 2012 Kony, Inc. All rights reserved. Page 437 of 785 Working with Services Kony Studio User Guide - 2.1 i. Select HTTP Headers tab in the screen shown below: ii. i. Click Add. A row gets added to the table. ii. Enter the value for ID. iii. Enter a Test Value. Test Value is the value that is used for testing the service. This is the value that is substituted during the service call while testing the service. iv. Select a value for Scope from the drop-down list. Scope denotes whether the value for the header is taken from the http request or a http session. 11. Select a value for Response encoding. The default value is UTF-8. For more information about different encoding schemes supported by Kony Studio, see Response encoding. 12. To encrypt your password in the service definition file that is stored on the middle ware server, select the Encrypt passwords while generating service definition file check box. 13. To ignore the XML response received in the XMLvalue field, select the Escape embedded xml in response check box. 14. To ignore the HTTP proxy configured in the application, select the Ignore HTTP Proxy check box. Note: Steps 12, 13, and 14 are optional. 15. Click Save icon on the toolbar. The service is created. 16. Click Get Response to fetch the response for the service. 17. The service hits the external data source with the test values provided for the input parameters. The response appears under the Response tab and the result is displayed in the Results tab. Copyright © 2012 Kony, Inc. All rights reserved. Page 438 of 785 Working with Services Kony Studio User Guide - 2.1 18. Click Generate Service Definition icon to generate a Service Definition File. The service definition file generated is specific to XML services and appears under services in the Applications View as shown below: A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. The individual information about each service is present in <service_id>.split files in the split_services folder. 19. The service definition file looks similar to the following: <application desc="" id="GetStockQuotes" name="" smscode=""> Copyright © 2012 Kony, Inc. All rights reserved. Page 439 of 785 Working with Services Kony Studio User Guide - 2.1 ...<app-config> ......<config-param name="APP_SMS_HEADER" value="null"/> ...</app-config> ...<services> ......<service cacheable="false" cacheduration="" id="getAddress" passwordencrypted="true" smscode="" smsenabled="false" type="plainxmlserviceConnector"> .........<service-config> ............<config-param name="endpointUrl" value="http://maps.google.com/maps/geo?q=$latitude, $longitude&amp;output=xml"/> ............<config-param name="postprocessorname" value=""/> ............<config-param name="preprocessorname" value=""/> ............<config-param name="urlprovider" value=""/> ............<config-param name="sockettimeout" value=""/> ............<config-param name="proxyname" value=""/> ............<config-param name="proxyport" value=""/> ............<config-param name="proxyusername" value=""/> ............<config-param name="responseEncoding" value="UTF8"/> .........</service-config> .........<service-input> ............<param datatype="number" encode="true" name="latitude" sms-name="" src="request" value=""/> ............<param datatype="number" encode="true" name="longitude" sms-name="" src="request" value=""/> .........</service-input> .........<service-output> ............<dataset id="searchresults" src="/kml/Response"> ...............<param datatype="string" format="None" formatvalue="" name="coordinates" sms-name="" src="Placemark/Point/coordinates/text()" target="response"/> ...............<param datatype="string" format="None" formatvalue="" name="address" sms-name="" src="Placemark/address/text()" target=""/> ...............<param datatype="string" format="None" formatvalue="" name="cntNameCode" sms-name="" src="Placemark/AddressDetails/Country/CountryNameCode/text()" target=""/> Copyright © 2012 Kony, Inc. All rights reserved. Page 440 of 785 Working with Services Kony Studio User Guide - 2.1 ...............<param datatype="string" format="None" formatvalue="" name="cntName" sms-name="" src="Placemark/AddressDetails/Country/CountryName/text()" target=""/> ............</dataset> .........</service-output> ......</service> ...</services> </application> 20. You can define as many services you want in your application. To use the services in your application, right-click on the required service, and select Add . The service gets added to the Selected Services folder. Right-click on the Selected Services folder to define a new service and at the same time add it to the Selected Services folder. 21. Use the Event Editor to invoke this service. 22. Map the data elements within the application with this service using the Mapping Editor. 23. Publish the Service Definition File. 24. Build the application. 25. Test the service output on emulators in the similar way you have tested for Web Services. Note: You cannot test the services on J2ME Emulator if the service is a secure service call. This is due to a SSL Certificate Issue on the J2ME platform. 14.10 Creating a Java Service A service that uses a custom Java connector is a Java service. The Java connector is a custom Java Class that implements the com.konylabs.middleware.common.JavaService interface. You must load the required Jar files to define a Java service. The Jar files contain the Java classes. The Java classes contain the Java methods. These methods have the logic defined that is required for a service. Java services are mostly used in conjunction with Scraper Services. Use Case You use Java services when the external data source has not exposed any services. To create a Java service, follow these steps: 1. Go to Applications view. 2. Right-click the application and select Service Definition. 3. Select Java Services. The Java Service Definition Editor appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 441 of 785 Working with Services Kony Studio User Guide - 2.1 4. In the Load Java Services Libraries pane, click Load to load the Java Library (jar file) that has the Java Class which implements the com.konylabs.middleware.common.JavaService interface. 5. In the Java Services pane, click Add to create a service. Copyright © 2012 Kony, Inc. All rights reserved. Page 442 of 785 Working with Services Kony Studio User Guide - 2.1 6. Enter a name for the service in the window that appears and click OK. 7. In the Java Service Details pane, enter the following details: i. Class Name - the Java class that has the method defined. ii. Method Name - the method name that needs to be invoked when this service call is made. iii. Preprocessor Class Name (optional) - the Preprocessor if required. iv. Postprocessor Class Name (optional) - the Postprocessor if required. v. Cachable - if you want the service to be cachable, i.e., the service response is stored in the cache for the specified duration and the next time the service call is made, the response is fetched from the cache. a. Cache Duration (sec) - the duration in seconds within which the service response is fetched from the cache. b. Timeout (in ms) - the duration in milli seconds after which the service call is timed out. 8. In the Edit Service Parameters pane, add: i. Input Parameters Define the Parameter name, Scope, Test Value, and Data Type for the input parameters. For more information, see Input Parameters. Copyright © 2012 Kony, Inc. All rights reserved. Page 443 of 785 Working with Services Kony Studio User Guide - 2.1 ii. Output Parameters. Define the Parameter name, Scope, Data Type, Format, and Format Value for the output parameters. For more information, see Output Parameters. Note: opstatus parameter is automatically created. This parameter indicates if the service call was successful or not. 0 indicates success and a non-zero value indicates failure. 9. Click Test in the Java Service Detail pane. This button is enabled only when you enter a valid Class Name in this pane. The service call is made with the defined input parameters and their test values. The specified method is executed internally. 10. The result of the service call is captured in the Result pane. 11. Click Save icon on the toolbar to save the service. The Java service is created. 12. Click Generate Service Definition icon to generate a Service Definition File. The service definition file generated is specific to Java services and appears under services in the Applications View as shown below. Copyright © 2012 Kony, Inc. All rights reserved. Page 444 of 785 Working with Services Kony Studio User Guide - 2.1 A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. The individual information about each service is present in <service_id>.split files in the split_services folder. 13. The service definition file looks similar to the following: <application desc="" id="GetStockQuotes" name="" smscode=""> ...<app-config> ......<config-param name="APP_SMS_HEADER" value="null"/> ...</app-config> ...<services> ......<service cacheable="false" cacheduration="" id="getStockQuoteDetails" smscode="" smsenabled="false" type="javaConnector"> .........<service-config> ............<config-param name="className" value="com.kony.scrapper.gc.ScrapperJavaService"/> ............<config-param name="methodName" value="getGenericScrapperData"/> ............<config-param name="preprocessorname" value=""/> ............<config-param name="postprocessorname" value=""/> ............<config-param name="sockettimeout" value=""/> .........</service-config> .........<service-input> ............<param datatype="string" format="None" formatvalue="" name="company" sms-name="" src="request" target="" value=""/> .........</service-input> .........<service-output> ............<param datatype="string" format="None" formatvalue="" name="prevClose" sms-name="" src="" target="response"/> Copyright © 2012 Kony, Inc. All rights reserved. Page 445 of 785 Working with Services Kony Studio User Guide - 2.1 ............<param datatype="string" format="None" formatvalue="" name="tradeTime" sms-name="" src="" target="response"/> ............<param datatype="string" format="None" formatvalue="" name="getStockQuoteDetails_url" sms-name="" src="" target="response"/> ............<param datatype="string" format="None" formatvalue="" name="opstatus" sms-name="" src="" target="response"/> ............<param datatype="string" format="None" formatvalue="" name="getStockQuoteDetails_cookie" sms-name="" src="" target="response"/> ............<param datatype="string" format="None" formatvalue="" name="lastTrade" sms-name="" src="" target="response"/> .........</service-output> ......</service> ...</services> </application> 14. Use the Event Editor to invoke this service. 15. Map the data elements within the application with this service using the Mapping Editor. 16. Publish the Service Definition File. 17. Build the application. 18. Test the service output on emulators in the similar way you have tested for Web Services. Note: You cannot test the services on J2ME Emulator if the service is a secure service call. This is due to a SSL Certificate Issue on the J2ME platform. 14.11 Creating a JSON Service A service that communicates with an external data source using JSON data connector over the HTTP protocol and returns a response in JSON format is known as a JSON Service. You must create a service definition file for the JSON services. You can use the JSON services in any case where you would use an XML service. But, the response of a JSON service is in a JSON format. 14.11.1 Concepts about JSON Connector Notations l JSON Object - {} l JSON Array - [] Copyright © 2012 Kony, Inc. All rights reserved. Page 446 of 785 Kony Studio User Guide - 2.1 Working with Services 14.11.1.1 Important Considerations l l JSON Array will consist of an array of JSON Objects or a blank array. JSON Object is a key value pair. The key is a String and value can be a String, number(int, float,double), JSON Object or JSON Array. l JSON sting will not contain attributes. l JSON path does not provide Axes like Xpath. 14.11.1.2 Selecting Elements Element elementname // Description Selects all child elements of the named Element. Selects elements in the document from the current element that match the selection no matter where they are. 14.11.1.3 Sample Code { "bookstore": { "book": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99 } Copyright © 2012 Kony, Inc. All rights reserved. Page 447 of 785 Kony Studio User Guide - 2.1 Working with Services ] } } 14.11.1.4 Example Path Expression bookstore (or) /bookstore bookstore/book Result Selects all the child elements of the bookstore element Selects all book elements that are children of bookstore Selects all book elements no matter where they are in the JSON string Selects all book elements that are descendant of the bookstore element, no matter where they are under the bookstore element //book bookstore//book 14.11.1.5 Predicates Predicates are used to find a specific element or an element that contains a specific value. Predicates are always embedded in square brackets. Path Expression bookstore/book[1] bookstore/book[last()] bookstore/book[last()-1] bookstore/book[position()<3] bookstore/book[price>35.00] bookstore/book[price>35.00]/title Result Selects the first book element that is the child of the bookstore element Selects the last book element that is the child of the bookstore element Selects the last but one book element that is the child of the bookstore element Selects the first two book elements that are children of the bookstore element Selects all the book elements of the bookstore element that have a price element with a value greater than 35.00 Selects all the title elements of the book elements of the bookstore element that have a price element with a value greater than 35.00 14.11.1.6 Operators Operator Description Example Result l > Greater than price>9.80 l >= < Greater than or equal to price>=9.80 Less than price<9.80 l true if price is 9.90 false if price is 9.80 true if price is 9.90 l false if price is 9.70 true if price is 9.00 l false if price is 9.80 l Copyright © 2012 Kony, Inc. All rights reserved. Page 448 of 785 Kony Studio User Guide - 2.1 Working with Services Operator Description Example Result l != Not equal price!=9.80 l false if price is 9.80 true if price is 9.80 l false if price is 9.90 l = Equal true if price is 9.90 price=9.80 To create a JSON service, follow these steps: 1. Go to Applications view. 2. Right-click the GetStockQuotes application and select Service Definition -> JSON Services. 3. Service Definition Editor appears as shown below: 4. Do any one of the following: a. Right-click Services and select Add. b. If you have defined a JSON service in the workspace, it will show up within the Restful Services folder. Expand the Restful Services folder and click on the service you want to add. Copyright © 2012 Kony, Inc. All rights reserved. Page 449 of 785 Working with Services Kony Studio User Guide - 2.1 5. In the New Service window, enter the name as getTemperature and click Finish. 6. Enter a URL that corresponds to the external data source. The Kony mobile application connects to this external data source through a JSON connector and fetches the response. For example, http://www.weather.yahoo.com. 7. Select the Http Method of the service. l GET l PUT l POST l DELETE. These are the standard Http Method. Choose a method that is appropriate. 8. Click Input Parameters and define the parameters for this service. for more information about defining input parameters, see Input Parameters. 9. Click Output Parameters and define the parameters for this service. for more information about defining output parameters, see Output Parameters. 10. Enter the optional values based on your requirement. o User ID o Password o Browse and select a Preprocessor Name o Browse and select a Postprocessor Name o URL Provider o Timeout (in ms) o Cachable and Cachable Duration o Http Proxy details 11. In the Service pane, enter the following information: i. User ID and Password - Provide this information if the external web service requires form/basic authentication. Copyright © 2012 Kony, Inc. All rights reserved. Page 450 of 785 Working with Services Kony Studio User Guide - 2.1 ii. Preprocessor Name - Enter the Preprocessor file name. iii. Postprocessor Name - Enter the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. iv. Data Provider Name - Enter the Data Provide class name. Note: For more information on Data Provider, see the section Data Provider. v. URL Provider - Enter the URL Provider file name. Note: URL Provider is a Java class that manipulates the URL or the parameters of the URL for the external data source. Click here to view a sample code for the URL Provider. vi. Timeout (in ms) - Specifies the maximum time (in milli seconds) the service waits for a response, before terminating the connection to the external data source. vii. Cachable - Specifies if the service response must be stored in the cache. viii. Cachable Duration - This option is enabled if you select the Cachable property. This property specifies the time duration in seconds. Note: If this service is Cachable and a call is made before the specified time duration, the service response is fetched from the Cache, else a fresh service call is made to fetch response from the server. ix. In the Server Authentication field, provide the authentication details of the server from which the service will be fetched. To enable NTLM and Proxy authentication configuration, refer Appendix Proxy and NTLM Authentication Configuration. x. In the Http Proxy area, specify the following: a. Name:URL of the Proxy Server from which the data is to be fetched.. b. Port: Port on which the Proxy server is configured. c. The Username and Password to access the proxy server. xi. Select appropriate Response encoding scheme. The default value is UTF-8. For more information about different encoding schemes supported by Kony Studio, see Response Encoding Schemes. Add HTTP Header (Optional). Add HTTP Header if you need to add a custom http header as required by the external data source. Copyright © 2012 Kony, Inc. All rights reserved. Page 451 of 785 Working with Services Kony Studio User Guide - 2.1 i. Select HTTP Headers tab in the screen shown below: ii. i. Click Add. A row gets added to the table. ii. Enter the value for ID. iii. Enter a Test Value. Test Value is the value that is used for testing the service. This is the value that is substituted during the service call while testing the service. iv. Select a value for Scope from the drop-down list. Scope denotes whether the value for the header is taken from the http request or a http session. 12. Select a value for Response encoding. The default value is UTF-8. For more information about different encoding schemes supported by Kony Studio, see Response encoding. 13. To encrypt the password in the service definition file that is stored on the middleware server, select the Encrypt passwords while generating service definition file check box. 14. To ignore the XML response received in the XMLvalue field, select the Escape embedded xml in response check box. 15. To ignore the HTTP proxy configured in the application, select the Ignore HTTP Proxy check box. Note: Steps 13, 14, and 15 are optional. 16. Click Save icon on the toolbar. The service is created. 17. Click Get Response to fetch the response for the service. 18. The service hits the external data source with the test values provided for the input parameters. The response appears under the Response tab and the result is displayed in the Results tab. Copyright © 2012 Kony, Inc. All rights reserved. Page 452 of 785 Working with Services Kony Studio User Guide - 2.1 19. Click Generate Service Definition icon to generate a Service Definition File. The service definition file generated is specific to JSON services and appears under services folder in the Applications View. 20. The service definition file looks similar to the following: <application desc="" id="JSONnLoopingServ" name="" smscode=""> <app-config> <config-param name="APP_SMS_HEADER" value="null"/> </app-config> <services> <service cachable="false" cacheduration="" id="getTemperature" passwordencrypted="true" smscode="" smsenabled="false" type="jsonConnector"> <service-config> <config-param name="endpointUrl" value="http://www.weather.yahoo.com"/> <config-param name="postprocessorname" value=""/> <config-param name="preprocessorname" value=""/> <config-param name="urlprovider" value=""/> <config-param name="sockettimeout" value=""/> <config-param name="proxyname" value=""/> <config-param name="proxyport" value=""/> <config-param name="proxyusername" value=""/> <config-param name="http.method" value=""/> <config-param name="responseEncoding" value="UTF-8"/> </service-config> <service-input/> <service-output> <param datatype="number" format="None" formatvalue="" name="opstatus" sms-name="" src="" target=""/> <param datatype="string" format="None" formatvalue="" name="errmsg" sms-name="" src="" target=""/> Copyright © 2012 Kony, Inc. All rights reserved. Page 453 of 785 Working with Services Kony Studio User Guide - 2.1 <param datatype="number" format="None" formatvalue="" name="httpStatusCode" sms-name="" src="" target=""/> </service-output> </service> </services> </application> 21. Use the Event Editor to invoke this service. 22. Map the data elements within the application with this service using the Mapping Editor. 23. Publish the Service Definition File. 24. Build the application. 25. Test the service output on emulators in the similar way you have tested for Web Services. 14.12 Creating a Composite Service Composite Service is a combination of two or more services. These services can be web services, XML services, or Java services. When you create a service as a combination of services, you can specify the order of execution for the services. The order can be sequential or concurrent. l l Sequential indicates that the services will be invoked in the order you specify. And also, the output of one service becomes an input to the next service. Concurrent indicates that the services are invoked independent of each other. Invoking and execution of one service does not affect the execution of other services. Note: For a composite service, you select the services (from the existing services) that need to be included in a composite service. You do not define the input and output parameters as they are already defined. Use Case You create Composite Services if you need to execute two or more services at the same time. To create a composite service, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 454 of 785 Working with Services Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Right-click the application and select Service Definition. 3. Select Composite Services. 4. Service Definition window appears as shown below: Note: All the services defined in the application appear in the Service Definition Editor under the Services pane. 5. Click Create under the Composite Services pane to create a composite service. 6. In the Composite Services Wizard: i. Enter a name for the Composite Service. ii. Select the services that you want to include in the Composite Service. iii. Select the mode of Execution. Possible values are Sequential or Concurrent. If you select Sequential, you can change the sequence of execution of the services using arrows. and Copyright © 2012 Kony, Inc. All rights reserved. Page 455 of 785 Working with Services Kony Studio User Guide - 2.1 iv. Click Finish. Note: You can also include an existing Composite Service while creating another Composite Service. 7. The created composite service appears under the Composite Services pane in the Service Definition Editor along with the services that are included in the composite service. Copyright © 2012 Kony, Inc. All rights reserved. Page 456 of 785 Working with Services Kony Studio User Guide - 2.1 8. Select the required composite service and specify the Pre-processor Name for that service if required. 9. Click Save on the toolbar. A composite service is created. Note: When the composite service is executed, Opstatus and errcode parameters are automatically created by Kony Studio. The OpStatus parameter is a combined result of the opstatus parameter of all the individual services within the composite service. 10. Click Generate Service Definition icon to generate a Service Definition File. The service definition file generated is specific to Composite services and appears under services in the Applications View as shown below. A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. Copyright © 2012 Kony, Inc. All rights reserved. Page 457 of 785 Working with Services Kony Studio User Guide - 2.1 The individual information about each service is present in <service_id>.split files in the split_services folder. 11. The service definition file looks similar to the following: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application smscode="" name="" id="GetStockQuotes" desc=""> ...<app-config/> ...<services> ......<service smsenabled="false" smscode="" type="CompositeConnector" id="getStocksComposite" cacheduration="" cachable="false"> ......<service-config> .........<config-param value="Sequential" name="exec_type"/> .........<config-param value="getStockQuoteDetails" name="service"/> .........<config-param value="getAddress" name="service"/> .........<config-param value="" name="preprocessorname"/> ......</service-config> ......<service-input/> ......<service-output/> ......</service> ...</services> </application> 12. Use the Event Editor to invoke this service. 13. Map the data elements within the application with this service using the Mapping Editor. 14. Publish the Service Definition File. 15. Build the application. 16. Test the service output on emulators in the similar way you have tested for Web Services. Note: You cannot test the services on J2ME Emulator if the service is a secure service call. This is due to a SSL Certificate Issue on the J2ME platform. 14.13 Creating a SAP Service Kony Studio allows you to access and use the external SAP services using the custom SAP Connector. A service that uses a custom SAP connector is a SAP service. You must load the required Business Application Programming Interface (BAPI) functions to define a SAP service. The BAPI files contain the SAP methods and functions. These methods have the logic defined that is required for a service. A BAPI is remotely enabled function module since it can be invoked from remote programs like standalone JAVA programs, web interface. The supported SAP Servers versions are SAP ECC5, SAP ECC 6. Copyright © 2012 Kony, Inc. All rights reserved. Page 458 of 785 Working with Services Kony Studio User Guide - 2.1 14.13.1 Configuring the SAP environment for Kony Studio To configure SAP Environment for IDE: 1. Copy the following files from the SAP installation and place them in <JDK_Installation_Path>/jre/ lib/ext folder: sapjco3.dll sapjco3.jar Note: If you have a Windows OS, copy the sapjco3.dll file. If you have a Linux or Unix environment, copy the sapjco3.so file. 2. Modify the config.ini file and add the following line at the end of the file: osgi.parentClassloader=ext This file is available at <Eclipse_Installation_Path>/configuration. 3. Restart Eclipse. To configure SAP for middleware 1. Ensure that you remove the comment for the following lines in the web.xml file present in the WEB-INF folder of middleware.war. <!-- remove the comment for SAP connector enabled <listener> <listenerclass>com.konylabs.middleware.common.SAPConnectorListener</list ener-class> </listener>--> 2. To run SAP on a linux server, you have to copy libsappjco3.so and sapjco3.jar in the <JDK_ Installation_Path>/jre/ lib/ext folder. 14.13.2 Creating a SAP Service To create a SAP service, follow these steps: 1. Go to Applications view. 2. Right-click the application and select Service Definition. 3. Select SAP Services. The SAP Service Definition Editor appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 459 of 785 Kony Studio User Guide - 2.1 Working with Services 4. Right-click the SAP Servers folder and select Add Server. The SAP Server Details screen appears. Note: You can also add a SAP service using the Enterprise Explorer View. Right-click the SAP Servers folder and select Add Server. The SAP Server details screen appears. 5. In the Connection tab, enter the following information: l Server Name: Add the name of the SAP Server to be loaded. l Connection Properties: You can choose either direct or load balanced. o o Direct: When you select Direct, you establish a direct connection to a server without using a message server. Provide the following information: n Application Server: Enter the host name of the provider system. n System Number: Enter the port name of the provider system. Load Balanced: When you select Load Balanced, you can use a message server. The message server processes the (Remote Function Call) RFC call and sends a request to a provider system which can process this request. Provide the following information: n System ID: Enter the ID of the SAP system. n Message Server: Enter the host name of the message server. n Message Server Port: Enter the port number of the message server. n Login Group: Enter the login group, if a log on group is defined for the URL. The message server searches for a definition in the list of log in groups and performs the load synchronization for this group. Copyright © 2012 Kony, Inc. All rights reserved. Page 460 of 785 Working with Services l Kony Studio User Guide - 2.1 Login Details: Add the username, password, and the Client ID using which you will logon to the system. 6. In the Advanced tab, enter the following: l l l l l SAPRouter String: Enter the address of the SAP router that is used to connect to a provider system. Connection CPIC Trace Level: Enter the trace level which you want to set. Available options are: l -1: Usage of the global CPIC trace level. l 0: no CPIC trace. l 1: minimal CPIC trace. l 2: full CPIC trace. l 3: full CPIC trace including data. To enable tracing on the RFC destination, select the RFC Trace checkbox. Peak Connection Limit: Enter the maximum number of simultaneous connections that should be active. Pool Capacity: Enter the maximum number of idle connections to be kept open. Copyright © 2012 Kony, Inc. All rights reserved. Page 461 of 785 Working with Services Kony Studio User Guide - 2.1 7. In the Security tab, enter the following: l To enable Secure Network Connection, select the Enable SNC checkbox. l sncNameR3: Enter the SNC name of the User Management Engine (UME). l sncQOPR3: Select a value between 1 and 9 to indicate the SNC level of security. l sncLib: Enter the path to library that provides the SNC service. Copyright © 2012 Kony, Inc. All rights reserved. Page 462 of 785 Working with Services Kony Studio User Guide - 2.1 8. Click Connect. You can view the added server and its corresponding business objects under the SAP Server folder. Note: If you are getting unsatisfied link error add argument "-Djava.library.path = <JDK_ Installation_Path>/jre/lib/ext/"under -vmargs in eclipse.ini file 9. Expand each node to view the child nodes of each Business Object. The child nodes of each parent node are loaded when you click on the node. The on-demand loading of each child prevents UI freeze. The Progress View displays the progress of each loading operation. 10. Select a BAPI function, to view the corresponding input and output parameters. The BAPI functions have input parameters of the following datatype: l Collection: Is a table consisting of multiple parameters where each parameter is displayed as a column in the right pane. To view the parameters of the collection in the left pane, expand the <Collection name>. You can add values for each parameter(column) in the rows provided below the parameter. You can add rows using the icon. To delete a row, select the row and click row values of each parameter using the up and down arrows provided. . You can move the Note: The parameters in the collection are displayed as an alphabetically sorted tree in the left pane. In the Right pane, the parameters are displayed according to the usage in the BAPI function. Scroll left or right to view all the parameters. l Record: A record consists of a list of parameters. To view the parameters that are a part of a record, expand the record. You can see the datatypes assigned to each parameter in the left pane. Assign corresponding values for each parameter in the Value column in the right pane. Copyright © 2012 Kony, Inc. All rights reserved. Page 463 of 785 Working with Services l Kony Studio User Guide - 2.1 Parameter: A parameter can be of the datatype string, number, or date. All the parameters of a BAPI function are displayed on the top most area in the right pane. If a BAPI function consists of records as well, the parameters of the BAPI function which are not a part of the record are displayed below the record. In a BAPI function without records, the parameters appear on the top. 11. You can additionally specify: i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. 12. After specifying all the input parameters of the BAPI function, press Execute to view the output parameters. The Input and Output Parameters of the BAPI function can be viewed by click the Input or Output Tabs present at the bottom of the right pane 13. Select a BAPI function, right-click, and select Add to Selected to add the method to the Selected BAPI Functions folder for a specified server. The Add to Selected option appears only if the BAPI function has already been loaded. The selected services are used by the device when the application is launched. 14. You can also perform the following additional actions: l Right-click a created SAP server and Disconnect or view the Properties configured for that server. 15. Click Generate Service Definition icon to generate a Service Definition File. The service definition file generated is specific to SAP services and appears under services in the Applications View. A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. The individual information about each service is present in <service_id>.split files in the split_services folder. 16. Use the Event Editor to invoke this service. Copyright © 2012 Kony, Inc. All rights reserved. Page 464 of 785 Working with Services Kony Studio User Guide - 2.1 17. Map the data elements within the application with this service using the Mapping Editor. 18. Publish the Service Definition File. 19. Build the application. 20. Test the service output on emulators in the similar way you have tested for Web Services. 14.14 Creating a Siebel Service Kony Studio enables you to use Business Object and Business Services hosted on a Siebel Server. You can use the Siebel services and objects to create your own custom services and objects. The supported Siebel server versions are 7.0 and above. 14.14.1 Configuring the Siebel environment for Kony Studio To configure Siebel Environment for IDE: 1. Copy the following files from Siebel installation and place them in <JDK_Installation_Path>/jre/ lib/ext folder: Siebel.jar SiebelJI_enu.jar 2. Modify the config.ini file and add the following line at the end of the file: osgi.parentClassloader=ext This file is available at <Eclipse_Installation_Path>/configuration. 3. Restart Eclipse. To configure Siebel Environment for middleware when it is hosted on Tomcat Server: 1. Copy the following files from Siebel installation and place them in <JDK_Installation_Path>/jre/ lib/ext folder: Siebel.jar SiebelJI_enu.jar To configure Siebel Environment for middleware when it is hosted on Weblogic Server: 1. Copy the following files from Siebel installation and place them in <weblogic>/middleware.ear/middleware.war/WEB-INF/lib folder: Siebel.jar SiebelJI_enu.jar Copyright © 2012 Kony, Inc. All rights reserved. Page 465 of 785 Working with Services Kony Studio User Guide - 2.1 14.14.2 Creating a Siebel Service To create a Siebel service, follow these steps: 1. Go to Applications view. 2. Right-click the application and select Service Definition. 3. Select Siebel Services. The Siebel Service Definition Editor appears. 4. Right-click the Siebel Servers folder and select Add Server. The Siebel Server Details screen appears. Note: You can also add a Siebel service using the Enterprise Explorer View. Right-click the Siebel Servers folder and select Add Server. The Siebel Server details screen appears. 5. Enter the following details in the Connection Tab: l Server Name: Specify the name of the Siebel server, to fetch the Business Objects and Services of the server. l Url: Specify the URL where the Siebel server is hosted. l User Name: Specify the username using which you can access the Siebel server. l Password: Specify the password using which you can access the Siebel server. l Language: Specify the Language Code for the Siebel server. The default language code is enu, i.e English. 6. Enter the following details in the Advanced Tab: l Connection Pool Size: Indicates the connection pool size. The Connection pool maintains a set of connections to a specific server process. Copyright © 2012 Kony, Inc. All rights reserved. Page 466 of 785 Working with Services l l l l Kony Studio User Guide - 2.1 Transaction TimeOut(ms): Indicates the transaction timeout (in milliseconds). Client Transaction Timeout(sec): Indicates the transaction timeout (in seconds) on the client side. Session Retries: Specifies the maximum number of retries attempted by the system when the Siebel Server cannot be connected. Encryption: Specifies whether encryption of transmissions is done using Java Cryptography Extension(JCE) or RSA (if the connection uses encryption) or there is no encryption at all 7. Click OK. All the Business Objects and the services of the host server are fetched. 8. Expand each node to view the child nodes of each Business Object / Business Service. The child nodes of each parent node are loaded when you click on the node. The on-demand loading of each child prevents UI freeze. The Progress View displays the progress of each loading operation. 9. Select a Business Object to view the corresponding tables. Each table comprises of parameters that are represented as columns in the right pane. The datatypes of each parameter are listed in the left pane. Business Objects are represented as following in Kony Studio. l Table: A table where each row is a record and each column is a parameter. l Record: A record is a single row of a table with multiple parameters l Parameter: A parameter is a single column of the table. A parameter has multiple values. 10. You can perform the following actions on a Business Object : l l Query: Enables you to query a table. For a table with multiple records, you can write a query that enables you to view only some parameters or records. To add a query, click the table in the left pane and click the Query button in the right pane. The Enter Search Query Expression dialog appears. Enter the Search Expression and click OK. To view all the values of the parameters of a record, leave the dialog blank and click OK. The values appear in the right pane. To enter a specific query, it should be of the format [<column name>]='xyz'. For a table with multiple records, if you just want to view a record with a parameter id with a value 8SIA-81827, enter the following query [id]='8SIA-81827'. Delete: Enables you to delete a record in a table. To delete a record, click the record and click the Delete button. Copyright © 2012 Kony, Inc. All rights reserved. Page 467 of 785 Working with Services l l Kony Studio User Guide - 2.1 Add: Enables you to add a record to the table. To add a record to a table, click the table in the left pane and click the Add button in the right pane to add a value to the record table. The Create Records dialog appears. Click to add values for parameters. Click to remove values from a parameter. You can move the values across the column using the up and down arrows. Update: Enables you to update records in a table. To update a record, click the table in the left pane and click the Update button in the right pane. The Update Records dialog appears. Click on the row / parameter (column) that you want to update and make the required changes. Click to add values for parameters. Click to remove values from a parameter. You can move the values across the column using the up and down arrows. Using the Search Expression field, search for parameters or values from a list of records. For example enter the Search expression as [id]='8SIA-81827', the table is populated with the record having id as 8SIA-81827. Important: Any change you make in the right pane using the Query / Delete / Add /Update buttons, is reflected on the service or object hosted at the server. 11. To view Business Services, click the Business Services folder expand each Business Service and view the Input and Output parameters of a service. You can view and modify the input parameters in the right pane. Each Business service has the following fields: l opcode: Is a pre-populated non editable field. This opcode is used for internal purposes to invoke a service. l service: Is a pre-populated field. It denotes the name of the service. l method: Is a prepopulated field. It denotes the method defined for the service. l sessionid: Specifies a session id to be used to make subsequent service calls. l l inargs: Specifies the input arguments for the Business Service. You can specify values for each parameter defined in inargs by expanding inargs and providing a value for each parameter in the Value column. outargs: Specifies the output arguments for a Business Service. This field is populated when you execute the service. 12. To execute the Business Service or to view the results of the service, click the Execute button in bottom half of the right pane. You can view the results of the query when you click the Result Tab at the bottom of the right pane. 13. Before pressing the Execute button, you can additionally specify: Copyright © 2012 Kony, Inc. All rights reserved. Page 468 of 785 Kony Studio User Guide - 2.1 Working with Services i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. Adding a Query Service to the Selected Services 1. To add a new query service, expand a Business Object. A "Query Service" is a service which on execution gives a result based on the search expression specified. 2. Right-click the table and select Add New Query Service. 3. Enter a valid service id for the Query Service. 4. Click OK. This service is added to the Selected Services folder. 5. Click the created query service. You can view the service details in the right-pane. 6. In the searchexpr field, enter the desired query in the searchexpr dialog. A search expression is of the form [<column name>]= '<value>' 7. Click OK. 8. To query a table by its fields, select fields and click the Selection Dialog appears. button in the Value column. The Fields Copyright © 2012 Kony, Inc. All rights reserved. Page 469 of 785 Working with Services Kony Studio User Guide - 2.1 9. Select the fields you want that are to be a part of the query result. Click OK. In the left pane observe that the fields selected are a part of the Return Values in Output Params. 10. To execute the service or to view the results of the created query service, click the Execute button in bottom half of the right pane. You can view the results of the query when you click the Result Tab at the bottom of the right pane. 11. Before executing the service, you can additionally specify: i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. Adding a New Create Service to the Selected Services 1. To add a new "Create Service", expand a Business Object. The "Create Service" allows you to add values for parameters, i.e., to create a new record. 2. Right-click the table and select Add New Create Service. Copyright © 2012 Kony, Inc. All rights reserved. Page 470 of 785 Working with Services Kony Studio User Guide - 2.1 3. Enter a valid service id for the Create Service. 4. Click OK. This service is added to the Selected Services folder. 5. Click the created service. You can view the service details in the right-pane. The Input Parameters are displayed in a tree format in the left pane and as a table in the right pane. The first table visible in the right pane contains the opcode, the name of the business object(bo), the name of the business collection(bc) and a session id which has to be specified for the service to make service calls. The INPUT table is present below the first table. 6. Specify additional records to be added in the INPUT Table. To add a record, click and specify values for the parameter. To remove a record , select the record and click . Move the records across the table using the up and down arrows. Note: Autogenerated fields which cannot be modified by the user are not visible in the INPUT table. 7. To execute the service or to view the results of the "Create Service", click the Execute button in bottom half of the right pane. You can view the results of the query when you click the Result Tab at the bottom of the right pane. 8. Before executing the service, you can additionally specify: i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. Adding a New Delete Service to the Selected Services 1. To add a new "Delete Service", expand a Business Object. The "Delete Service" allows you to delete records using a search expression. 2. Right-click the table and select Add New Delete Service. 3. Enter a valid service id for the Delete Service. 4. Click OK. This service is added to the Selected Services folder. Copyright © 2012 Kony, Inc. All rights reserved. Page 471 of 785 Working with Services Kony Studio User Guide - 2.1 5. Click the created "Delete service". You can view the service details in the right-pane. The Input Parameters are displayed in a tree format in the left pane and as a table in the right pane. The first table visible in the right pane contains the opcode, the name of the business object(bo), the name of the business collection(bc) and a session id which has to be specified for the service to make service calls. 6. Click the searchexpr field, and in the value column, click the button and specify a search expression using which a record will be deleted. For example, if you enter the search expression as [id] ='1234', the record with the id 1234 will be deleted. 7. To execute the service or to view the results of the "Delete Service", click the Execute button in bottom half of the right pane. You can view the results of the query when you click the Result Tab at the bottom of the right pane. 8. Before executing the service, you can additionally specify: i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. Adding a New Update Service to the Selected Services 1. To add a new "Update Service", expand a Business Object. The "Update Service" allows you to update values for parameters. 2. Right-click the table and select Add New Update Service. 3. Enter a valid service id for the Update Service. 4. Click OK. This service is added to the Selected Services folder. 5. Click the created "Update service". You can view the service details in the right-pane. The Input Parameters are displayed in a tree format in the left pane and as a table in the right pane. The first table visible in the right pane contains the opcode, the name of the business object(bo), the name of the business collection(bc) and a session id which has to be specified for the service to make service calls. The INPUT table is present below the first table. Copyright © 2012 Kony, Inc. All rights reserved. Page 472 of 785 Working with Services Kony Studio User Guide - 2.1 6. In the searchexpr field, click the button and specify a search expression using which a record will be updated. For example, if you enter the search expression as [id]='1234', the record with the id 1234 will be updated. 7. Specify the records to be updated in the INPUT Table. To update a record, click and specify values for the parameter. To remove a record , select the record and click . Move the records across the table using the up and down arrows. Note: Autogenerated fields which cannot be modified by the user are not visible in the INPUT table. 8. To execute the service or to view the results of the "Update Service", click the Execute button in bottom half of the right pane. You can view the results of the query when you click the Result Tab at the bottom of the right pane. 9. Before executing the service, you can additionally specify: i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. Adding a Business Service to the Selected Services 1. To add a Business Service, expand the Business Services folder. 2. Right-click the service name and select Add To Selected. The service is added in the Selected Service folder. 3. Expand the added Business Service and view the Input and Output parameters of a service. You can view and modify the input parameters in the right pane. Each Business service has the following fields: l opcode: Is a prepopulated non editable field. This opcode is used for internal purposes to know which service is to be called. l service:Is a prepopulated field. It denotes the name of the service. l method: Is a prepopulated field. It denotes the method defined for the service. Copyright © 2012 Kony, Inc. All rights reserved. Page 473 of 785 Working with Services l l l Kony Studio User Guide - 2.1 sessionid: Specifies a session id to be used to make subsequent service calls. inargs: Specifies the input arguments for the Business Service. You can specify values for each parameter defined in inargs by expanding inargs and specifying a value for each parameter in the Value column. outargs: Specifies the output arguments for a Business Service. This field is populated when you execute the Service. 4. To execute the Business service or to view the results of the service, click the Execute button in bottom half of the right pane. You can view the results of the query when you click the Result Tab at the bottom of the right pane. 5. Before pressing the Execute button, you can additionally specify: i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. Using the Created Services 1. Click Generate Service Definition icon to generate a Service Definition File. The service definition file generated is specific to Siebel services and appears under services in the Applications View. A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. The individual information about each service is present in <service_id>.split files in the split_services folder. 2. Use the Event Editor to invoke this service. 3. Map the data elements within the application with this service using the Mapping Editor. 4. Publish the Service Definition File. 5. Build the application. 6. Test the service output on emulators in the similar way you have tested for Web Services. Copyright © 2012 Kony, Inc. All rights reserved. Page 474 of 785 Working with Services Kony Studio User Guide - 2.1 14.15 Creating a WebSphere MQ Service [Mainframe] Kony Studio enables you to create configurations to connect to the WebSphere MQ Server. Using these configurations you can create a service to send and receive messages from the WebSphere MQ server. The supported WebSphere MQ server version are 7.0 and above. 14.15.1 Configuring WebSphereMQ for Kony Studio To configure WebSphere MQEnvironment for IDE: 1. Copy the following files from the WebSphere MQ installation and place them in <JDK_Installation_ Path>/jre/ lib/ext folder: CL3Export.jar CL3Noexport.jar com.ibm.mq.jar com.ibm.mq.jmqi.jar com.ibm.mqjms.jar dhbcore.jar fscontext.jar jms.jar jndi.jar ldap.jar providerutil.jar rmm.jar 2. Modify the config.ini file and add the following line at the end of the file: osgi.parentClassloader=ext This file is available at <Eclipse_Installation_Path>/configuration. 3. Restart Eclipse. 14.15.2 Creating a WebSphere Service Using the procedure below you create default configurations to access the WebSphere Server. To create a WebSphere MQ configuration, follow these steps: 1. Go to Applications view. 2. Right-click the application and select Open Service Definition. 3. Select Mainframe Services. The Mainframe Services Explorer appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 475 of 785 Working with Services Kony Studio User Guide - 2.1 4. Right-click the JMS/MQ Servers folder and select Add. The Server Details screen appears. Note: You can also add a JMS/MQ service using the Enterprise Explorer View. Right-click the JMS/MQ Servers folder and select Server. The Server Details screen appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 476 of 785 Working with Services Kony Studio User Guide - 2.1 5. Enter the Id of the service being created. 6. Consumer Timeout: Indicates the duration in milliseconds the connector tries to establish a connection or waits for the message. 7. Message Expire Timeout: Indicates the number of milliseconds after which a message is discarded from the destination queue by the WebSphere MQ server. 8. Persistent: Specifies whether the message is persistent in a queue. Persistent message will be written to permanent storage like database or file. When a queue manager fails, persistent messages will be recovered to the queue. While non-persistent messages can't be recovered as they will not be stored anywhere. 9. Destination type: Specifies the methods of messaging. The possible values are Queue or Topic. Select Queue for point to point messaging where there is one receiver of the message. Select Topic for one to many messaging. Topic uses the publish or subscribe model of messaging. 10. Source Type: Specifies how to acquire the connection objects to WebSphere MQ server. You can specify any one of the following values: l wmq: Specifies that the WebSphereMQ Server is directly connected. The Queue/Topic Objects are fetched directly from the WebSphereMQ server. When you select the Source Type as wmq, the following fields are available: l l Provider Url: Specifies the name of the JMS/Java provider. Host: Specifies the WebSphereMQ host name i.e. the name of the computer on which the server is running. Copyright © 2012 Kony, Inc. All rights reserved. Page 477 of 785 Working with Services l l l l l l l Kony Studio User Guide - 2.1 Port: Specifies the port number. Specify the port value if a firewall is setup that allows connections only from specific ports. Channel: Specify the channel name to be used to send and receive a message. Channels are used to transmit messages between queue managers. There are different type of channels such as point-to-point channels, cluster channels, and client channels. Specify names according to the channel types. The channel name is of the form KONY.CHANNEL. Connection Mode: Specifies the connection mode to connect to the queue manager. The client option enables you to connect to the queue manager using TCP/IP. The bindings option enables you to connect to the queue manager directly using Java Native Interface. Queue Manager: Specifies the name of the queue manager of the target system. Queue managers manage the queues and messages. The naming convention for a queue manager is QM_KONY. Ensure that the queue manager name never contains a dot . character. Destination: Specifies the name of the destination object that specifies target and the source of the messages. ldap: Specifies that connection objects for the WebSphereMQ Server are obtained from the light weight directory based directory server. The Queue/Topic objects are fetched from the WebSphereMQ Server using the filesystem based directory server. fsds:Specifies that connection objects for the WebSphereMQ Server are obtained from the filesystem based directory server. The Queue/Topic objects are fetched from the WebSphereMQ Server using the filesystem based directory server. If you specify the source type as ldap or fsds, the following options are available: l l l Provider Url: Specifies the name of the JMS/Java provider. Lookup Factory: Specifies the lookup name using which the connection factory instance is established. The naming convention for a lookup factory is as follows: kony_ test_cf_ldap. Lookup Destination: Specifies the destination JNDI name to look up the destination administered object. 11. Click OK. Configurations to connect to the WebSphereMQ Server are created. These configurations can be used to send and receive messages to/from the server To create a service, follow the steps below: Copyright © 2012 Kony, Inc. All rights reserved. Page 478 of 785 Working with Services Kony Studio User Guide - 2.1 1. Right-click the Services folder and select Add. The Service Details Screen appears. 2. Specify the id of the service to be created. 3. Each service can be of the following types: l send: The service created will send messages to the Queue Manager. l receive: The service created will receive messages from the Queue Manager. l send_receive: The service created will send messages and receive messages or after a certain time duration. 4. Click OK. The created service details can be viewed in the right pane. 5. Depending on the service type specified in step 3, the input parameters in the right pane differ. Copyright © 2012 Kony, Inc. All rights reserved. Page 479 of 785 Working with Services Kony Studio User Guide - 2.1 6. For type set as l l l send service specify: o mqconfig: Specifies the configuration created to send messages to the server. The configurations added using the previous procedure are visible in the drop-down list. o message: Specifies the message to be sent to the Queue Manager. o isTransacted: If set to true, the service uses a JMS transacted session. i.e only operations performed in a certain session are included in the transaction. receive service specify: o mqconfig: Specifies the configuration created to receive messages from the server. The configurations added using the previous procedure are visible in the drop-down list. o isTransacted: If set to true, the service uses a JMS transacted session. i.e only operations performed in a certain session are included in the transaction. o selector: Specifies a message header [string] and allows you to receive messages based on the message header. Only messages whose headers match the selector are received. send_receive service specify: o mqconfig: Specifies the configuration created to send messages to the server. The configurations added using the previous procedure are visible in the drop-down list. o mqconfig_receive: Specifies the configuration created to receive messages from the server. The configurations added using the previous procedure are visible in the dropdown list. o message: Specifies the message to be sent to the Queue Manager. o isTransacted: If set to true, the service uses a JMS transacted session. i.e only operations performed in a certain session are included in the transaction. 7. You can additionally specify: i. Preprocessor Class - Specifies the Preprocessor file name. ii. Postprocessor Class - Specifies the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. 8. After specifying all the input parameters of the service, press Execute to view the output parameters. 9. Click Generate Service Definition icon to generate a Service Definition File. The service definition file generated is specific to mainframe services and appears under services in the Applications View. A Service Definition file has information common to all the services like the server configurations, wsdl configurations etc. The individual information about each service is present in <service_id>.split files in the split_services folder. 10. Use the Event Editor to invoke this service. Copyright © 2012 Kony, Inc. All rights reserved. Page 480 of 785 Working with Services Kony Studio User Guide - 2.1 11. Map the data elements within the application with this service using the Mapping Editor. 12. Publish the Service Definition File. 13. Build the application. 14. Test the service output on emulators in the similar way you have tested for Web Services. 14.16 Creating a Looping Connector A Looping Connector is a type of service that runs in a loop for the specified number of times. The specified service gets invoked and executed multiple times till the loop ends. You must have at least one service defined for you to create a looping connector. The looping connector is useful in the following cases: l when you want to fetch the stock price and display it to the user constantly l when you want to retrieve the weather details and keep updating it at regular intervals l when you want to display the current news to the users with constant updates. In these cases, the service defined for retrieving such information runs in a loop and fetches the information constantly. To define a looping connector, follow these steps: 1. Go to Applications View. 2. Select the required application. 3. Right-click and select Service Definition -> Looping Connector. 4. Click Create in the Looping Connector Service Definition window. 5. The Looping Connector window appears. i. Enter an ID for the looping service. ii. Select the order of Execution: Sequential or Concurrent. l l Sequential: the service gets executed sequentially, i.e, once the first service call is complete it gets invoked again. Concurrent: the service gets executed concurrently i.e., the service is executed simultaneously to retrieve the data from the external data source. iii. All the services defined in the application are listed in the window. Select the service that you want to execute in a loop. iv. Click Finish. 6. In the Service Definition window, select the appropriate Lopping Service and define the following details: Copyright © 2012 Kony, Inc. All rights reserved. Page 481 of 785 Working with Services Kony Studio User Guide - 2.1 i. (Optional) Browse and select a Preprocessor that you want to be applied to the looping service. For more information about a preprocessor, see Preprocessor. ii. (Optional) Browse and select a Postprocessor that you want to be applied to the looping service. For more information about a preprocessor, see Postprocessor. iii. Define the Configuration Params. These can be defined statically in the Service Definition Editor or provided dynamically at the run time as request parameters. l l l l Loop Count (Mandatory) - specifies the number of times the service included in the looping service must get executed. Alternatively, you can pass the value to the "loop_ count" of the request parameter. Looping Separator (Mandatory) - specifies the character that indicates the separator that separates different looping services in the service definition file. Alternatively, you can pass the value to the "loop_separator" of the request parameter. Breakout param name - specifies if there are any breakout parameters for the execution of the looping service. The breakout parameter will be a part of the result returned from the service call within a loop. Alternatively, you can pass the value to the "dependent_ tag" of the request parameter. Breakout param value - specifies the value for the breakout parameter of the looping service. If the value of the breakout parameter returned from the service matches with the given value, it breaks out of the loop. Or you can pass the value to the "dependent_ value" of the request parameter. Loop Count and Loop Separator denote a fixed loop and Breakout param name and Breakout param value are used to specify the criteria for the breakout. The breakout occurs when the specified criteria is met. For example, if the fixed loop is 10, and the breakout parameter is given and if the criteria is met at loop count 5, then it breaks out of the loop. At runtime, looping service must receive at least one request parameter, whose value is separated by value given in the loop separator. For example, if the request parameter 'tickers' has a value 'MSFT,GOOG,APPL', the looping separator is ',' in this case. 7. Click and generate the Service Definition File. The looping service (s) is defined. Important: dependent_tag should be as Param in returned result , it will not work if dependent_tag is in Dataset or inner Records. 14.17 Service Definition Template The Service Definition Template is a prototype that defines the mandatory skeleton of the services. The services defined in the Service Definition Template can be imported and used within an application. When you define services in the Service Definition Template, you must define the following: l Input Parameters (mandatory) l Output Parameters (mandatory) l Http Headers (optional). The services within the Service Definition Template do not include: Copyright © 2012 Kony, Inc. All rights reserved. Page 482 of 785 Working with Services l External data source from which the service fetches a response. l Preprocessors and Postprocessors. l XPath to be applied to the output parameters. Kony Studio User Guide - 2.1 14.17.1 Use Case You define a Service Definition Template in an application when you are not aware of the following: l Type of service (SOAP or XML)/Data Connector l External data source. You can design the user interface (consisting of Forms and widgets) and use the services within the Service Definition Template to bind them to the forms and form elements using the Mapping Editor. After you decide on the type of service (SOAP or XML) and the external data source, you can open the Service Definition Editor of SOAP or XML services and import the services into the application so that they can be reused. Note: You cannot use the Service Definition Template for Java Services. 14.17.2 Advantages The following are the advantages of Service Definition Template: l l Allows you to develop a generic application framework and perform the UI bindings with the service parameters even though you have not defined the actual service. Reduces the development effort as the prototype of the services is pre-defined. 14.17.3 Create a Service Definition Template You can create a Service Definition Template that defines services and their associated parameters. To create a service template, follow these steps: 1. Open Kony Studio and go to Applications View. 2. Right-click the application for which you want to create a service template. A context menu appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 483 of 785 Working with Services Kony Studio User Guide - 2.1 3. Select Service Definition -> Define service template. The Service Definition Template window appears as shown below: 4. Right-click Services and select Add Service. Copyright © 2012 Kony, Inc. All rights reserved. Page 484 of 785 Working with Services Kony Studio User Guide - 2.1 The New Service window appears as shown below: 5. Enter a name for the service and click Finish. The created service is added under Services in the Service Definition Template window as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 485 of 785 Working with Services Kony Studio User Guide - 2.1 6. In the Params section pane, add appropriate data for the Http Headers, Input Parameters, and Output Parameters. Note: Http Headers tab is optional and you can use it to add custom http headers as required by the external data source. For detailed information about Input Parameters and Output Parameters, click here. 7. Repeat steps 1 to 6 to define more services. 8. Click the Build icon in the toolbar. The Service Definition Template is created and a confirmation screen appears as shown below: 9. The created template will be listed in the Applications View under the Application Name -> Services > template as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 486 of 785 Working with Services Kony Studio User Guide - 2.1 Note: The services created in the Service Definition Template are available in the Event Editor (to invoke services) and Mapping Editor (to attach data elements to the service parameters). 14.17.4 Map the Parameters of the Service Template You can use the service template and map the UI widgets in the user interface to the parameters defined in the service template. To map the parameters of the service template from the Event Editor, follow these steps: 1. Open the Event Editor for the UI widget that you want to add mapping for. For example, you can open the Event Editor for a button widget by selecting onclick in the Events section of the Properties tab. Copyright © 2012 Kony, Inc. All rights reserved. Page 487 of 785 Working with Services Kony Studio User Guide - 2.1 2. In the Define Action Sequence pane, right-click Action Sequence and select Invoke Service. 3. In the Invoke Service pane, select the service template you created from the Select Service dropdown list as shown below: 4. Click Open Mapping Editor. The Mapping Editor opens. 5. Perform the required mapping and click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 488 of 785 Kony Studio User Guide - 2.1 Working with Services The mapping of the UI widgets to the parameters defined in the service template is complete. 14.17.5 Export the Service Definition Template After you have generated the service definition file and performed the UI mapping, you must export the service definition file to create a Service Definition Template. To export the service template from the IDE, follow these steps: 1. Open servicetemplate.tf (available under Application Name -> Services -> template). The Service Definition Template window opens. 2. In the Services pane, Click icon (export icon) as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 489 of 785 Working with Services Kony Studio User Guide - 2.1 The Select services to export window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 490 of 785 Working with Services Kony Studio User Guide - 2.1 3. Select the service (s) to export and click OK. The Export window appears as shown below: 4. Navigate to the location where you want to save the service template and click OK. The Service Definition Template is successfully created (as servicedef-template.xml file) and a confirmation message appears as shown below: The Service Definition Template can now be imported into the Service Definition Editor of SOAP or XML to populate the parameters section. 14.17.6 Import the Service Template After you decide on the type of service (SOAP or XML) and the external data source, you can open the Service Definition editor of SOAP or XML and import the service template to populate the parameters section. Important: When you try to import the Service Definition Temple, Kony Studio looks for a servicedef-template.xml file. This file is created only when you export the service definition file. Hence, exporting the service definition file is mandatory. To import the service template into the Service Definition editor, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 491 of 785 Working with Services Kony Studio User Guide - 2.1 1. Open Kony Studio and go to the Applications View. 2. Right-click the application for which you created the service template. A context menu appears as shown below: 3. Select Service Definition -> Web Services (SOAP) or XML Services as required. The Service Definition Editor appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 492 of 785 Working with Services 4. Click Kony Studio User Guide - 2.1 icon (import icon). The import window appears as shown below: Navigate to the location where you have exported the service template and select the template. Click Open. 5. The Select service templates to import window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 493 of 785 Working with Services Kony Studio User Guide - 2.1 Select the required service (s)and click OK. 6. If the names of the services in the application and those defined in the Service Definition Template are same, you have to provide a new name for the service while importing it into the application to prevent overwriting of the existing service. Copyright © 2012 Kony, Inc. All rights reserved. Page 494 of 785 Working with Services Kony Studio User Guide - 2.1 7. The service template is imported into the Service Definition Editor and the appropriate parameters (Headers, Input, and Output) are populated. 8. You can now add information for the other parameters in the Service Definition editor or choose to edit the parameters. Note: You must enter the URL for the service to enable the fields under Http Headers, Input Parameters, and Output Parameters tabs. 14.18 Publishing Services Once the Service Definition File is generated, the services in the application can be tested using the emulators. To do this, you must publish the Service Definition file. When you publish the Service Definition file, the metadata of all the services will be available on the Kony Application Server, so that the services can be used by the application. When the application makes a service call: l The service is checked in the published Service Definition file. l Connection is established with the external data source based on defined parameters. l Desired response is retrieved from the external data source, based on the request. l Information is displayed on the emulator/device. Copyright © 2012 Kony, Inc. All rights reserved. Page 495 of 785 Working with Services Kony Studio User Guide - 2.1 To publish the Service Definition file, follow these steps: Important: The procedure given below is applicable on Tomcat, Weblogic, and WebSphereServer. 1. Go to Applications View. 2. Right-click the application and select Publish. A context menu appears as shown below: 3. Select Publish -> Services. 4. Publish Services window appears as shown below: 5. Check the checkbox Use URL defined in Properties -> Kony Server. Note: Make sure appropriate Kony application server credentials (Server Name/IP Address and the Port number) are set under the Kony Server tab of the project properties. T OR You can manually enter the following information if you leave the checkbox unchecked: Copyright © 2012 Kony, Inc. All rights reserved. Page 496 of 785 Working with Services Kony Studio User Guide - 2.1 i. Protocol - Select the protocol as per your requirement from http or https. ii. Server Name/IP Address - Provide Kony application server name or the IP address. iii. Server Port - Provide the listening port of the Kony Application Server. 6. Click Finish. Publishing of service happens in the background as shown below: The KonyServer prompts for a Userid and Password. The default user id and password is set to admin/admin_1234. Copyright © 2012 Kony, Inc. All rights reserved. Page 497 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15. Developing Offline Applications Offline Applications enable you to access services on your device if it is not connected to a network (data). This basically provides you with the flexibility to define a service for your application which can be accessed by the user when the device is not connected to a network. You can access the following Data sources offline by using the Kony Sync tool chain View. l Sky Data Objects l Databases l Web Services l SAP Services (Will be made available in the next release) l Siebel Services (Will be made available in the next release) 15.1 Prerequisites for Accessing Offline Data Sources To develop offline applications using Kony Sync tool chain, follow these steps: 1. Install Kony Studio 5.0.12 GA or later. 2. Install the Kony Sync plugins from: http://developer.kony.com/updatesite/55/ Copyright © 2012 Kony, Inc. All rights reserved. Page 498 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 3. Ensure that you configure the Sky Server such that the Data Objects can be fetched and explored. 4. Ensure that you are connected to the Sky Server directly or either through VPN. 5. Please ensure that the Sky Gateway is setup with below SAP parameters l l gw/netstat - this needs to be set to blank gw/alternative_hostnames - This needs to be set to include the external IP address of the Enterprise firewall Please contact your SAP Administrator to set the above parameters. If the Sky Gateway is not set with the appropriate SAP parameters, you might see the error below: Copyright © 2012 Kony, Inc. All rights reserved. Page 499 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 6. Minimum Sky MEAP Server installed in the SAP namespace should be 24.02.10 or above. Follow these prerequisites if your Datasource is an RDBMS: 1. To connect to an RDBMS datasource, ensure that you have downloaded the required drivers for a particular database on your computer. 2. To allow SQL Server Express to accept remote connections, please follow these steps: a. Click Start, Programs, Microsoft SQL Server 2005/2008 and select SQL Server Configuration Manager. b. Select SQL Server Network Configuration. c. Double click on Protocols for SQLEXPRESS. Copyright © 2012 Kony, Inc. All rights reserved. Page 500 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 d. Enable TCP/IP Protocol if it is disabled. e. Right click TCP/IP and select Properties. f. Scroll down to IP all make sure TCP Dynamic Ports is blank and that TCP Port is set to 1433. g. Click OK. h. Make sure that port: 1433 is enabled on your VDS firewall. i. Mixed mode authentication must also be enabled for remote connections. j. Make sure that the SQL Browser is enabled and running. When using SQL Express you will also need to open UDP port 1434. 15.2 Introduction to Kony Sync Kony Sync Framework is a comprehensive synchronization platform that enables developers to add synchronization capabilities to mobile applications. Kony Sync Framework solves the problem of how to synchronize any type of data in any relational database management store using any protocol over any topology. Fundamental to Kony Sync Framework is the ability to support offline and collaborative data between devices and the server. Kony Sync Architecture Copyright © 2012 Kony, Inc. All rights reserved. Page 501 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 For more information about Kony Sync, refer the Kony Sync Framework Getting Started Guide. 15.3 Creating a SkyMobile Datasource This chapter provides an introduction to SkyMobile and lists the procedures to import Sky data objects and using the SyncConfiguration view to import those data objects. 15.4 Introduction to Sky Mobile You can now access Sky Data Objects within your application using the Sky Data Explorer view which is integrated in Kony Studio. With Sky Technologies, Kony can immediately offer customers a significantly broader range of B2E solutions, including certified integration with SAP environments. SAP customers in particular benefit from Sky's ability to deploy from inside SAP and domain expertise in B2E environments. Meanwhile, Sky Technologies customers benefit from Kony's broad array of pre-built B2C and B2E applications, its broad and deep multi-channel application platform, and its mobile application management/mobile device management solutions. Sky Architecture 15.4.1 Sky Data Object Explorer Kony Studio allows you to access and use the Sky objects using the custom Sky Data Object Explorer. A Sky Data Object typically has the following hierarchy: Copyright © 2012 Kony, Inc. All rights reserved. Page 502 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 Data Objects: This is the first node available in Sky Data explorer, once the server is connected. Sky Data Object explorer allows you to refresh and view the Data Object. It allows you to view Data Object synchronization properties. It also offers an option for you to import the Data Objects to Kony project. A Data Object (DOB) enables linking of one or more local database (LDB) definitions together. Following are the primary advantages: l Ability to process multiple LDB synchronization requests in a single request. l Process complete transactions i.e. all inter-related data together. l l Enables the use of a data profile facility to automatically control the distribution of data to remote Application Servers. Incorporate Binary objects (BOBs) into a Data Object definition, using classification. Tables: This is the next node for a Data Object tree. Sky Data Object explorer allows you to refresh, expand and collapse the Table tree node so as to display the underlying components. It allows you to view Table properties, Table definition and Table key relationships (field to field mapping between parent and child tables). You can also view all the columns and the column type of the table in the table tree node. Binary object: Sky Data Object explorer allows you to view binary objects attached/associated to a table/Data Object. It allows user to refresh, expand and collapse the Binary object tree node so as to display the underlying components. It allows user to view Binary object properties and Binary object details. The Sky Data Object explorer allows the user to create and save new Sky server profiles and connect, edit or delete existing server profiles. It also allows user to connect to more than one Sky servers at the same time. 15.5 Viewing the Sky Data Explorer Sky Data Explorer is available as a tab, next to the Enterprise Explorer. Copyright © 2012 Kony, Inc. All rights reserved. Page 503 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 If you cannot view the Sky Explorer, 1. Navigate to Window > Show View > Other. 2. In the filter text area, enter Sky Data Explorer. 3. Click OK. 4. The Sky Data Explorer View appears. 15.6 Connecting to a Sky Server Before connecting to a Sky Server ensure that you: 1. Copy the following files from the SAP installation and place them in <JDK_Installation_Path>/jre/ lib/ext folder: sapjco3.dll sapjco3.jar Note: If you have a Windows OS, copy the sapjco3.dll file. If you have a Linux or Unix environment, copy the sapjco3.so file. 2. Modify the config.ini file and add the following line at the end of the file: osgi.parentClassloader=ext This file is available at <Eclipse_Installation_Path>/configuration. 3. Restart Eclipse. To add a Sky Server, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 504 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 1. Go to the Sky Data Explorer view. 2. Right-click the Sky Servers folder and select Add Server. The SAP Server Details screen appears. 3. In the Connection tab, enter the following information: l Server Name: Add the name of the SAP Server to be loaded. l Connection Properties: You can choose either direct or load balanced. o o Direct: When you select Direct, you establish a direct connection to a server without using a message server. Provide the following information: n Application Server: Enter the host name of the provider system. n System Number: Enter the port name of the provider system. Load Balanced: When you select Load Balanced, you can use a message server. The message server processes the (Remote Function Call) RFC call and sends a request to a provider system which can process this request. Provide the following information: n System ID: Enter the ID of the SAP system. n Message Server: Enter the host name of the message server. n Message Server Port: Enter the port number of the message server. n Login Group: Enter the login group, if a log on group is defined for the URL. The message server searches for a definition in the list of log in groups and performs the load synchronization for this group. Copyright © 2012 Kony, Inc. All rights reserved. Page 505 of 785 Developing Offline Applications l Kony Studio User Guide - 2.1 Login Details: Add the username, password, and the Client ID using which you will logon to the system. 4. In the Advanced tab, enter the following: l l l l l SAPRouter String: Enter the address of the SAP router that is used to connect to a provider system. Connection CPIC Trace Level: Enter the trace level which you want to set. Available options are: l -1: Usage of the global CPIC trace level. l 0: no CPIC trace. l 1: minimal CPIC trace. l 2: full CPIC trace. l 3: full CPIC trace including data. To enable tracing on the RFC destination, select the RFC Trace checkbox. Peak Connection Limit: Enter the maximum number of simultaneous connections that should be active. Pool Capacity: Enter the maximum number of idle connections to be kept open. Copyright © 2012 Kony, Inc. All rights reserved. Page 506 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 5. In the Security tab, enter the following: l To enable Secure Network Connection, select the Enable SNC checkbox. l sncNameR3: Enter the SNC name of the User Management Engine (UME). l sncQOPR3: Select a value between 1 and 9 to indicate the SNC level of security. l sncLib: Enter the path to library that provides the SNC service. Copyright © 2012 Kony, Inc. All rights reserved. Page 507 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 6. Click Connect. You can view the added server and its corresponding Data Objects under the Sky Servers folder. Important: Ensure that you configure the Sky Server such that the Data Objects can be fetched and explored. 7. Expand each node to view the child nodes of each Data Object. The child nodes of each parent node are loaded when you click on the node. The on-demand loading of each child prevents UI freeze. The Progress View displays the progress of each loading operation. 8. You can also perform the following additional actions: l l Right-click a created Sky server and Disconnect or view the Properties configured for that server. Right click and add additional Sky Servers. 15.7 Working with the Kony SyncConfiguration View After you have configured and connected to the Sky Server, you can import all the Sky Data Objects as Sync Objects using the Kony SyncConfiguration view. The sections below describe the procedures to use the SyncConfiguration view. 15.7.1 Viewing the Kony SyncConfiguration View The SyncConfiguration view is next to the Emulators. Using the SyncConfiguration View, you can map and use SOAP, SAP, Database tables, Siebel, or Sky Objects as offline services. To view the SyncConfiguration view, follow these steps: 1. Navigate to Window > Show View > Other. 2. In the filter text area, enter Sync. 3. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 508 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 4. The SyncConfiguration View appears. 15.7.2 Creating a New SyncConfiguration You can import the Sky Data Objects using the SyncConfiguration view. To create a new Sync configuration for Sky Data Objects, follow these steps: 1. Navigate to the SyncConfiguration view. 2. To create a new Sync configuration, click . The Create SyncConfiguration dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 509 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 3. The SyncConfiguration Name, Application ID, and Application Name fields are pre populated based on the name of your application. You can change the name of the configuration created and ID of the application based on the ID created for the application. 4. Set a namespace for the Sync Configuration. The namespace you enter here will be used for the naming convention of the generated offline services. 5. Click Finish. The SyncConfiguration view appears. 15.7.2.1 Adding a DataSource After you add a Sync configuration, you need to add a Datasource. When you add a Datasource, you specify the source from which the objects/services will be imported and will be available as an offline service. To add a Datasource follow these steps: 1. Right-click the DataSources icon, and select Add DataSource. 2. Specify a name for the DataSource configuration that you are creating. 3. Select the Type of DataSource from which the objects are imported from. For importing Sky Objects, set the Type as Sky. 4. Select the Server from which you want to import the objects from. If you have configured multiple servers for Sky in the Sky Data Explorer, a list of servers appears. Select any one of the servers for which you are creating a DataSource for. Copyright © 2012 Kony, Inc. All rights reserved. Page 510 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 5. Click Finish. The DataSource added appears as follows. 6. You can edit the details of a DataSource or delete a DataSource as well. 15.7.2.2 Adding a Sync Scope from Sky Data Objects After you define a DataSource for Sky, you can add a SyncScope using the created data source. Doing so enables you to create a SyncScope for each of the Sky Data Objects. When you create a SyncScope, you can create an application from the SyncScope objects and create offline services. Copyright © 2012 Kony, Inc. All rights reserved. Page 511 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 1. Right click SyncScopes and select Add SyncScope from Sky Data Objects. 2. Select the application for which you want to add a DataObject to a SyncScope. 3. Do any of the following: l To create a SyncScope for the Data Object, select any one of the displayed Data Objects in the left pane and click . Copyright © 2012 Kony, Inc. All rights reserved. Page 512 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications l To remove a Data Object whose Sync Scope is added, select the Data Object from the right pane and click l . To create a SyncScope for all the Data Objects, select any one of the displayed Data Objects in the left pane and click l . To remove all the Data Object whose Sync Scope is added, select any Data Object from the right pane and click . 4. Click Finish. All the added SyncScopes are listed under the SyncScopes folder. 15.7.3 Adding or Editing the Sync Object In the Sync Configuration View, you can do the following: l Add a SyncObject or a SyncAttribute l Edit a SyncObject Important: You can add or edit attributes, relationships and objects that are present within the same SyncScope. 15.7.3.1 Adding a SyncObject In the SyncConfiguration view, after you have added a DataSource and then a SyncScope, add a SyncObject in the existing list of Objects. To do so, 1. Right-click the created SyncScope and select Add Sync Object. Copyright © 2012 Kony, Inc. All rights reserved. Page 513 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 2. Specify the name for the SyncObject. 3. Click Finish. Important: It is mandatory to define a SyncAttribute for any new SyncObject that is created. If you do not do so, an error appears when you generate the application forms or offline services. 15.7.3.2 Adding a Sync Attribute Every SyncObject created has attributes. For example a SyncObject comprising the summary of a data can have attributes such as month, year, and owner of the object 1. Right click the SyncObject and select Add Sync Attribute. 2. Enter a name for the SyncAttribute, the datatype for the attribute, select whether the value can be set to null, the maximum length of the data in the field, select whether the field is an autogenerated field, such as customer id field like 1,2,3 which have counters and are autogenerated, and whether the attribute would be key of the SyncObject table. Copyright © 2012 Kony, Inc. All rights reserved. Page 514 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 3. Click Finish. The added SyncAttribute appears under the SyncObject. 15.7.3.3 Editing a SyncObject Every SyncObject can have multiple attributes, relationship with other SyncObjects. Editing Attributes To edit attributes that are already part of a SyncObject, do the following: 1. Right click the SyncObject you for which you want to edit the attributes for and select Edit. The Edit SyncObject dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 515 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 2. All the attribute fields that are editable are enabled. You can do any of the following: l l l l Name: Name of the attribute in the SyncObject. Each attribute is automatically named when you import a Data Object, you can rename the attributes for a SyncObject using this field. Is Key: You can set the value in this field to true or false . Set this field to true to enable an attribute of an Object to be the key for that particular object. Once you set an attribute as a key its values have to be unique. Type: Specifies the datatype of an attribute. Choose an appropriate datatype for an attribute from the list of available. Is Nullable: You can set the value in this field to true or false. Set this field to true to specify whether a certain field can be left blank without any value specified in it. l Max Length: Specifies the maximum number of characters an attribute can have. l Autogenerated: Specifies whether a field is an auto generated field. l Use the Filter field to filter the attributes of an Object and edit the fields accordingly. l You can also add an attribute using the add ( ) button and fill the corresponding fields accordingly. To remove an attribute, select the attribute row or name and click the delete( ) button. You can change the order of the attributes by selecting the attribute and using the up or Copyright © 2012 Kony, Inc. All rights reserved. Page 516 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications down arrows. To insert a new attribute before another attribute click after another attribute click . To insert an attribute . 3. Click Finish. Editing Relationships To edit relationships that are already part of a SyncObject or to add a new relationship between SyncObjects, do the following: 1. Right click the SyncObject for which you want to edit the relationships for and select Edit. The Edit SyncObject dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 517 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 2. Select Relationships from the left pane. The following dialog appears. 3. You can edit the existing relationships between SyncObjects. l Target Object: Target SyncObject to which thecurrent SyncObject creates a relationship with. Click the click OK. l l l l button, to change the Target Object. Select a Target Object from the list and Relationship: Specify the type of relationship between the Source attribute (record) in the SyncObject to the Target attribute(child record) of another SyncObject. Target Attribute: Specifies the attribute of the other SyncObject with which you want to relate your Source Attribute to. Source Attribute: Specify the attribute of the SyncObject you want to link the Target Attribute to. Cascade: Set this value to true or false. Setting this to true implies that when you delete a record in the parent table, it will subsequently delete all the records in the child table as well. 4. You can also add a relationship using the add ( ) button and fill out the corresponding fields accordingly. To remove a relation, select the attribute row or name and click the delete( ) button. You can change the order of the relationships by selecting the relationship and using the up or down arrows. To insert a new relationship before another relationship click another relationship click . To insert a relationship after . Copyright © 2012 Kony, Inc. All rights reserved. Page 518 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.8 Using the Sky Objects in your Application You can import and use the Sky Objects in your application. For an application you can do the following: l Generating Application Forms. l Generating and using offline services. 15.8.1 Troubleshooting Sky Connectivity Issues If I face errors while connecting to the Sky SAP Server, what do I do? 1. Check whether all the required jars are present under the java ext folder used by eclipse. To know the version used by eclipse, navigate to Help > About Eclipse> Installation Details > Configurations and check the -vm parameter. For example: -vm C:/Program Files (x86)/Java/jdk1.6.0_27/jre/bin/client/jvm.dll Copyright © 2012 Kony, Inc. All rights reserved. Page 519 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 2. Ensure that you are connected to the Sky Server directly or either through VPN. 3. If the Sky Gateway is not set with the appropriate SAP parameters, you might see the error below: Please ensure that the Sky Gateway is setup with below SAP parameters l l gw/netstat - this needs to be set to blank gw/alternative_hostnames - This needs to be set to include the external IP address of the Enterprise firewall Please contact your SAP Administrator to set the above parameters. 4. Minimum Sky MEAP Server installed in the SAP namespace should be 24.02.10 or above. Copyright © 2012 Kony, Inc. All rights reserved. Page 520 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 I am unable to view or import the Data Objects from the Sky Server, what do I do? Ensure that you configure the Sky Server such that the Data Objects can be fetched and explored. 15.9 Creating an Database Datasource You can now access tables, system tables, and view tables created on your database server and import the tables using the SyncConfiguration view. You can use the data ported in the SyncConfiguration view and map them to widgets or fields in your application and create an offline application. 15.9.1 Connecting to a Database Server To add a Database Server, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 521 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 1. Go to the Enterprise Explorer view. 2. Right-click the Databases folder and select Add Database. The Database Details screen appears. 3. Enter the following information: l l Display Name: Enter the name for the database server. After the database details are added, a connection to the server is created with the name entered in this field. In the Database Details area, specify the following: o Vendor: Select the type of the Database you want to connect to. o URL: Specify the URL where the Database is hosted. n For MY SQL, replace $HOST with the IP address of the machine where the server is hosted, replace $PORT with the port number on which the server is running, and replace $DATABASE_NAME with the name of the database from which you want to port the tables from. n For Oracle, replace $HOST with the IP address of the machine where the server is hosted, replace $PORT with the port number on which the server is running, Copyright © 2012 Kony, Inc. All rights reserved. Page 522 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 and $SID with the SID of the database from which you want to port the tables from. o n For MSSQL, replace $HOST with the IP address of the machine where the server is hosted, replace $PORT with the port number on which the server is running, and replace $DATABASE_NAME with the name of the database from which you want to port the tables from. n For POSTGRESQL, replace $HOST with the IP address of the machine where the server is hosted, replace $PORT with the port number on which the server is running, and replace $DATABASE_NAME with the name of the database from which you want to port the tables from. Enter the user credentials for the server where the database is hosted. Note: Specify the credentials only when the user and password details are not given in the url. l l In the Driver Details area, specify the following: o Driver jar: Browse and select the appropriate database drivers based on the database vendor selected. o Driver Class Name: Browse and select the driver class name from the jar selected in the above step. Specify Optional connection parameters to the server if any. To specify an additional optional connection parameter click . In the Key column, specify the additional key in the URL for example: maxconns, ldapver, and timeout. Specify the value of the key in the right column. To delete a connection parameter select the key and click change the orders of the connection parameters. l . Use the up or down arrows to Click Test Connection. The Testing connection Progress can be viewed in the Progress View.A connection successful dialog appears. Click OK. 4. Click Finish. 5. The database configuration you create appears under the Database folder. Right click the created configuration and click Connect. Copyright © 2012 Kony, Inc. All rights reserved. Page 523 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 6. Expand each node to view the child nodes of each Data Object. The child nodes of each parent node are loaded when you click on the node. The on-demand loading of each child prevents UI freeze. The Progress View displays the progress of each loading operation. 7. You can also perform the following additional actions: l l Right-click a created Database server and Disconnect or view the Properties configured for that server. Right click and add additional Database Servers. 15.10 Working with the Kony SyncConfiguration View After you have configured and connected to the database, you can import all the RDBMS tables as Sync Objects using the Kony SyncConfiguration view. The sections below describe the procedures to use the SyncConfiguration view. 15.10.1 Kony SyncConfiguration View The SyncConfiguration view is available as a tab, next to the Emulators. Using the SyncConfiguration View, you can map and use Database, SOAP, SAP, Siebel, or Sky Objects as offline services. To view the SyncConfiguration view, follow these steps: 1. Navigate to Window > Show View > Other. 2. In the filter text area, enter Sync. 3. Click OK. 4. The SyncConfiguration View appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 524 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 15.10.2 Creating a New SyncConfiguration To create a new Sync configuration for Databases, follow these steps: 1. Navigate to the SyncConfiguration view. 2. To create a new Sync configuration, click . The Create SyncConfiguration dialog appears. 3. The SyncConfiguration Name, Application ID, and Application Name fields are pre populated based on the name of your application. You can change the name of the configuration created and ID of the application based on the ID created for the application. 4. If the Sync configuration has any persistent scope, select the appropriate database type. Note: The intermediate persistent sync store(Replica and Upload Databases) scripts are created based on the Persistent Database Type selected. 5. Set a namespace for the Sync Configuration. This namespace will be used for the naming convention of the client side generated code. 6. Click Finish. The SyncConfiguration view appears. 15.10.2.1 Adding a DataSource After you add a Sync configuration, you need to add a datasource. When you add a datasource, you specify the source from which the objects/services will be imported. To add a datasource follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 525 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 1. Right-click the DataSources icon, and select Add DataSource. 2. Specify a name for the DataSource configuration that you are creating. 3. Select the Type of DataSource from which the objects are imported from. For importing Database Objects, set the Type as Database. 4. Select the Server from which you want to import the objects from. If you have configured multiple database servers in the Enterprise Explorer, a list of servers appears. Select the specific server for which you are creating a datasource for. Copyright © 2012 Kony, Inc. All rights reserved. Page 526 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 5. Click Finish. The DataSource added appears as follows. 6. You can edit the details of a DataSource or delete a DataSource as well. 15.10.2.2 Adding a Sync Scope After you define a datasource, you can add a SyncScope using the created data source. Doing so enables you to create SyncObjects comprising required tables from the datasource. You can create multiple SyncScopes and have desired SyncObjects within the scope. When you create a SyncScope, you can create an application from the SyncScope objects and create offline services. 1. Right click SyncScopes and select Add SyncScope. The Add SyncScope dialog appears. 2. Specify any name for the SyncScope. Copyright © 2012 Kony, Inc. All rights reserved. Page 527 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 3. Specify a namespace for the SyncScope. The namespace can be of any format, for example com.kony. 4. Select the appropriate datasource from the drop-down. 5. Select the type of Sync Strategy. For more information about the types of Sync Strategies refer the Kony Sync Framework Getting Started Guide. 6. Set the Change Tracking Policy(CTP) if you want to track the changes happening in the server database. Set CTP as Kony Sync Server, if you want to SyncServer to track the changes. Select Provided by Datasource if you have a provision where changes made to the database can be notified to SyncServer. For Database this would be like a timestamp column which updates for any change made to the row. 7. If CTP is provided by datasource, then select the Change Tracking Columns supported by the Database. Select the Last Updated Timestamp check box when you have column which represents the incremental changes. Select the Soft Delete Flag check box when the database has the column which represents soft deletes. 8. In case of conflicts between the data at the client and server end, specify any of the following: l l l Client Wins: The changes on the client side take precedent over the changes on the server side. Server Wins: The changes on the server side take precedent over the changes on the client side. Custom: Enables you to upload an Interceptor class which comprises the logic or policy for conflict resolution. 9. Conflict Interceptor Class: Enables you to browse and upload an interceptor class which comprises the logic or policy for conflict resolution. For more information about interceptors and the types of interceptors, refer the Kony Sync Framework Getting Started Guide. 10. Click Finish. The created SyncScope appears below the SyncScopes folder. Copyright © 2012 Kony, Inc. All rights reserved. Page 528 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.10.3 Importing Columns to SyncObjects Each SyncObject is created from existing tables in a database schema. Using the SyncConfiguration view, you can import SyncAttributes(columns) from one SyncObjects(tables) to another SyncObject. To import columns to SyncObjects, do the following: 1. Right click the SyncObject and select Import Columns. The Import Columns dialog appears. 2. Specify the table from which you want to import the columns from. 3. To filter the columns by name, enter a filter for the column. This step is optional. 4. Click Query. 5. Do any of the following: l To add a column to a SyncObject, select any one of the displayed columns in the left pane and click . l To remove a column added, select the column from the right pane and click . l To add all the columns, select any one of the displayed columns in the left pane and click l To remove all the columns added, select the columns from the right pane and click . . 6. Click Finish. All the additional columns are added under the SyncObject. 15.10.4 Adding or Editing the Sync Object In the Sync Configuration View, you can do the following: l Add a SyncObject or a SyncAttribute l Edit a SyncObject l Create Relationships l Create Filters Copyright © 2012 Kony, Inc. All rights reserved. Page 529 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 Important: You can add, edit, or create relationships/attributes that are present within the same SyncScope. 15.10.4.1 Adding a SyncObject from Tables After you have added a Sync datasource and a SyncScope, you can add SyncObjects from tables of the configured Database server. To add a SyncObject and SyncAttributes from Tables: 1. Right click the SyncScope and select Add SyncObject from Tables. 2. Select the Schema from which you want to import the tables from. 3. The following steps are optional: l l Set a filter for querying the database. Doing so saves computation time since all the tables from a schema are not fetched. Set the type of table that you want to fetch. The types of tables are, System tables, Tables, and View tables. View tables are nothing but tables that have join data from several tables thus creating a new view of it. Say you have a database with salaries and you need to do some complex statistical queries on it. Once you have set the Table Type filter, you can also set filters based on the name of the table. For example, entering a Name Filter %categories% will display only the Categories table. Copyright © 2012 Kony, Inc. All rights reserved. Page 530 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 4. Click Query. The Available tables are listed in the left pane. 5. Do any of the following: l To create a SyncScope for a Table, select any one of the displayed Table in the left pane and click l . To remove a Table whose Sync Scope is added, select the Table from the right pane and click . l To create a SyncScope for all the Tables, select any one of the displayed Tables in the left pane and click l . To remove all the Tables whose Sync Scope is added, select the Tables from the right pane and click . 6. If you want to Import Attributes from the Table columns as well, select the Import Attributes from Column Names checkbox. Copyright © 2012 Kony, Inc. All rights reserved. Page 531 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 7. Click Finish. All the added Tables are listed under the SyncScopes folder. 8. Once the SyncAttributes are imported, they need to be edited to select the Autogenerated fields and to map the change tracking columns if selected. For more explanation Refer to Editing SyncObject > Editing Attributes. 15.10.4.2 Adding a SyncObject In the SyncConfiguration view, after you have added a datasource and then a SyncScope, add a SyncObject in the existing list of Objects. To do so, 1. Right-click the created SyncScope and select Add Sync Object. 2. Specify the name for the SyncObject. 3. Click Finish. Important: It is mandatory to define a SyncAttribute for any new SyncObject that is created. If you do not do so, an error appears when you generate the application forms or offline services. Copyright © 2012 Kony, Inc. All rights reserved. Page 532 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.10.4.3 Adding a Sync Attribute Every SyncObject created has attributes. For example a SyncObject comprising the summary of a data can have attributes such as month, year, and owner of the object 1. Right click the SyncObject and select Add Sync Attribute. 2. Enter a name for the SyncAttribute, the datatype for the attribute, select whether the value can be set to null, the maximum length of the data in the field, select whether the field is an autogenerated field, such as customer id field like 1,2,3 which have counters and are autogenerated, and whether the attribute would be key of the SyncObject table. 3. Click Finish. The added SyncAttribute appears under the SyncObject. Copyright © 2012 Kony, Inc. All rights reserved. Page 533 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.10.4.4 Editing a SyncObject Every SyncObject can have multiple attributes, relationship with other SyncObjects. Editing Attributes To edit attributes that are already part of a SyncObject, do the following: 1. Right click the SyncObject you for which you want to edit the attributes for and select Edit. The Edit SyncObject dialog appears. 2. All the attribute fields that are editable are enabled. You can do any of the following: l l l l l Name: Name of the attribute in the SyncObject. Each attribute is automatically named when you import a Data Object, you can rename the attributes for a SyncObject using this field. Database Column: The column in the database. Is Key: You can set the value in this field to true or false. Set this field to true to enable an attribute of an Object to be the key for that particular object. Once you set an attribute as a key its values have to be unique. For SyncObjects derived Type: Specifies the datatype of an attribute. Choose an appropriate datatype for an attribute from the list of available. Is Nullable: You can set the value in this field to true or false. Set this field to true to specify whether a certain field can be left blank without any value specified in it. Copyright © 2012 Kony, Inc. All rights reserved. Page 534 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications l Max Length: Specifies the maximum number of characters an attribute can have. l Autogenerated: Specifies whether a field is an auto generated field. l Use the Filter field to filter the attributes of an Object and edit the fields accordingly. l l If Change Tracking coumns are selected while creating the syncscope, map them to the corresponding Attributes You can also add an attribute using the add ( ) button and fill the corresponding fields accordingly. To remove an attribute, select the attribute row or name and click the delete ( ) button. You can change the order of the attributes by selecting the attribute and using the up or down arrows. To insert a new attribute before another attribute click after another attribute click . To insert an attribute . 3. Click Finish. Editing Relationships To edit relationships that are already part of a SyncObject or to add a new relationship between SyncObjects, do the following: 1. Right click the SyncObject for which you want to edit the relationships for and select Edit. The Edit SyncObject dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 535 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 2. Select Relationships from the left pane. The following dialog appears. 3. You can edit the existing relationships between SyncObjects. l Target Object: Target SyncObject to which the current SyncObject creates a relationship with. Click the click OK. l l l l button, to change the Target Object. Select a Target Object from the list and Relationship: Specify the type of relationship between the Source attribute (record) in the SyncObject to the Target attribute (child record) of another SyncObject. Target Attribute: Specifies the attribute of the other SyncObject with which you want to relate your Source Attribute to. Source Attribute: Specify the attribute of the SyncObject you want to link the Target Attribute to. Cascade: Set this value to true or false. Setting this to true implies that when you delete a record in the parent table, it will subsequently delete all the records in the child table as well. This applies only to client side or device database. 4. You can also add a relationship using the add ( ) button and fill out the corresponding fields accordingly. To remove a relation, select the attribute row or name and click the delete( ) button. You can change the order of the relationships by selecting the relationship and using the up or down arrows. To insert a new relationship before another relationship click another relationship click . To insert a relationship after . Copyright © 2012 Kony, Inc. All rights reserved. Page 536 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 Editing Filters To add additional filters that for a SyncObject or to edit any existing filters for a SyncObject, do the following: 1. Right click the SyncObject for which you want to edit the filters for and select Edit. The Edit SyncObject dialog appears. 2. Select Filters from the left pane. There are two types of filters, a Client Side Filter and a Server Side Filter. Apply a server side filter when you want to filter the data fetched from the Enterprise Datasource to a replicated database. Apply a Client side filter when you want data to be filtered while downloading the data to the client database. Basically client side filters are to be used when filter values have to be changed dynamically from the client side code. Based on the strategy of the scope client side filter are applied either on Enterprise datasource(OTA)r on Replica database(Persistent Strategy). For example if you want only Customer ID's which are greater than 10 but less than 20 to be fetched, apply a server side filter. To set a filter do the following: l Filter Attribute: Set the SyncAttribute using which you filter the data. Using the example stated above the SyncAttribute would be CustomerID. l Condition: Set a condition using which the data will be filtered. l Specify the Values using which you want to filter the data in Value1 and Value 2 Columns. Copyright © 2012 Kony, Inc. All rights reserved. Page 537 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications Important: For mathematical conditional operators you can just specify one value in the Value1 column. 3. Click Finish. 4. You can also add a filters using the add ( ) button and fill out the corresponding fields accordingly. To remove a filter, select the attribute row or name and click the delete( ) button. You can change the order of the filters by selecting the filter and using the up or down arrows. To insert a new filter before another filter click . To insert a filter after another filter click . Note: All filters will be applied with AND composite. We can use EXPRESSION filter for OR composites. 15.11 Using the Database Tables in your Application You can import and use the Database Tables in your application. For an application you can do the following: l Generating Application Forms. l Generating and using offline services. 15.11.1 Troubleshooting Database Connectivity Issues If I am "unable to connect to the configured Database Server" what to do? 1. To connect to an RDBMS Datasource, ensure that you have downloaded the required drivers for a particular database on your computer. 2. To allow SQL Server Express to accept remote connections, please follow these steps: a. Click Start, Programs, Microsoft SQL Server 2005/2008 and select SQL Server Configuration Manager. b. Select SQL Server Network Configuration. c. Double click on Protocols for SQLEXPRESS. d. Enable TCP/IP Protocol if it is disabled. e. Right click TCP/IP and select Properties. f. Scroll down to IP all make sure TCP Dynamic Ports is blank and that TCP Port is set to 1433. g. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 538 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications h. Make sure that port: 1433 is enabled on your VDS firewall (instructions for enabling firewall ports can be found here). i. Mixed mode authentication must also be enabled for remote connections. j. Make sure that the SQL Browser is enabled and running. When using SQL Express you will also need to open UDP port 1434. 15.12 Creating a WebService Datasource Services imported through Enterprise Explorer can be used to in the sync configuration as a datasource. You can use the data ported in the SyncConfiguration view and map them to widgets or fields in your application and create an offline application. Using the Enterprise Explorer View 1. To add a WSDL service, follow these steps: a. Right-click on Web Services, and select Add Web Service WSDL. The WSDL Service dialog appears. b. Enter a name for the WSDL service. c. In the WSDL URL field, click to add an *.wsdl file. d. Enter the Basic Credentials for the service(If applicable). e. Click OK 15.13 Working with the Kony SyncConfiguration View After you have added the WSDL, you can import all the web services as Sync Objects using the Kony SyncConfiguration view. The sections below describe the procedures to use the SyncConfiguration view. 15.13.1 Kony SyncConfiguration View Using the SyncConfiguration View, you can map and use SOAP, SAP, Siebel, Database, or Sky Objects as offline services. To view the SyncConfiguration view, follow these steps: 1. Navigate to Window > Show View > Other. 2. In the filter text area, enter Sync. 3. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 539 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 4. The SyncConfiguration View appears. 15.13.2 Creating a New SyncConfiguration You can create or load sync configuration file using the the SyncConfiguration view. To create a new Sync configuration for Databases, follow these steps: 1. Navigate to the SyncConfiguration view. 2. To create a new Sync configuration, click . The Create SyncConfiguration dialog appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 540 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 3. The SyncConfiguration Name, Application ID, and Application Name fields are pre populated based on the name of your application. You can change the name of the configuration created and ID of the application based on the ID created for the application. 4. If the Sync configuration has any persistent scope, select the appropriate database type. Note: The intermediate persistent sync store(Replica and Upload Databases) scripts are created based on the Persistent Database Type selected. 5. Set a namespace for the Sync Configuration. The namespace you enter here will be used for the naming convention of the generated offline services. 6. Click Finish. The Sync Configuration structure appears in SyncConfiguration view. 15.13.2.1 Adding a DataSource After you add a Sync configuration, you need to add a Datasource. When you add a Datasource, you specify the source from which the services will be imported. To add a Datasource follow these steps: 1. Right-click the DataSources icon, and select Add DataSource. 2. Specify a name for the DataSource configuration that you are creating. 3. Select the Type of DataSource from which the services are imported from. For importing Web Services, set the Type as Web Service. Copyright © 2012 Kony, Inc. All rights reserved. Page 541 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 4. Click Finish. The DataSource added appears as follows. 5. You can edit the details of a DataSource or delete a DataSource as well. To add specific services from a WSDL to a DataSource, do the following: 1. Right click the created Datasource and select Edit. The Import Services dialog appears. 2. Expand the WSDL and select the specific services that you want to import. 3. Click Finish. All the selected services appear under the created DataSource. 4. You have to specify input and output parameters for each of the services you have added for a DataSource. To do so, double click a service that is present under a created DataSource. The service definition dialog appears. 5. Information associated with the service is populated into the Service and Request tab of the Response/Request pane in the Service Definition Tool. Copyright © 2012 Kony, Inc. All rights reserved. Page 542 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 Since we are not aware of the parameters that the end user provides as an input in the application, we provide a substitute parameter in the code of the request pane and provide appropriate input parameters in the Input Parameters pane. 6. In the Service pane, enter the following information: i. Soap Action - This is auto populated from the WSDL. ii. User ID and Password - Provide this information if the external web service requires form/basic authentication. iii. URL Provider - Enter the URL Provider file name. Note: URL Provider is a Java class that manipulates the URL or the parameters of the URL for the external data source. Click here to view a sample code for the URL Provider. iv. Timeout (in ms) - Specifies the maximum time (in milli seconds) the service waits for a response, before terminating the connection to the external data source. v. In the Server Authentication field, provide the authentication details of the server from which the service will be fetched. To enable NTLM and Proxy authentication configuration, refer Appendix Proxy and NTLM Authentication Configuration. vi. Select appropriate Response encoding scheme. The default value is UTF-8. For more information about different encoding schemes supported by Kony Studio, see Response Encoding Schemes. 7. Add HTTP Header (Optional). Add HTTP Header if you need to add a custom http header as required by the external data source. Copyright © 2012 Kony, Inc. All rights reserved. Page 543 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 i. Select HTTP Headers tab in the screen shown below: ii. Click Add. A row gets added to the table. iii. Enter the value for ID. iv. Enter a Test Value. Test Value is the value that is used for testing the service. This is the value that is substituted during the service call while testing the service. v. Select a value for Scope from the drop-down list. Scope denotes whether the value for the header is taken from the http request or a http session. 8. Add Input Parameters to the Service. Input parameters are the parameters that you pass to the service and are used during a service call. All the services do not have input parameters. We provide the input parameters based on the elements that are present in the Request pane. i. Select Input Parameters tab in the screen shown below: ii. Click Add. A row gets added to the table. iii. Enter the value for ID as the parameter name in the request pane. iv. Enter a Test Value. Test Value is the value of the parameter that is used for testing the service. This is the value that is substituted in place of the actual parameter during a service call. . v. Select a value for Scope from the drop-down list. Scope denotes the scope of the parameter, if it is limited to request or a session. vi. Select a value for Datatype from the drop-down list. Datatype denotes the type of the parameter. You can add an additional datatype ; collection. For more information about collections, refer Collection. Copyright © 2012 Kony, Inc. All rights reserved. Page 544 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 vii. Select True or False for Encode. Specifies if the URL needs to be encoded or not viii. If you need to delete a parameter row, select the parameter row you want to delete and click Delete. This action removes the parameter row from the list of service parameters. 9. Test the Service. After you configure a service, you have the option to test the service from the IDE itself. When you click Get Response in the Service pane, a service call is made with the input parameters. The service call returns data, that is, output parameters. By testing the service in the IDE, you know if the service call is fetching the data from the server as per your requirement. i. Request pane shows the request code that is passed to the URL as a service call. ii. The response fetched is shown in the Response tab. iii. Select the XML code in the window, right-click and select Format to present the code in a readable format. 10. Add Output Parameters to the Service response. We format the output parameters based on the response we get from the tested service call, that is displayed in the Response pane. a. Select Output Parameters tab in the screen shown below: i. Click Add. A row gets added to the table. ii. Enter values for ID. It is advisable to create an ID that easily identifies the elements that we would like to capture from the response. iii. Apply XPath for extracting the required elements from the response of the service call. XPath is used to navigate through elements and attributes in an XML document. For more information about XPath, see http://www.w3schools.com/xpath/. Copyright © 2012 Kony, Inc. All rights reserved. Page 545 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 iv. Select a value for Scope from the drop-down list. Scope denotes the scope of the parameter, if it is limited to response or session. v. Select a value for Datatype from the drop-down list. Datatype denotes the type of the parameter. vi. Collection ID - Groups data elements under the specified parameter as a collection. Collection is created to assign grouped data to segment or a table in the UI. vii. Record ID - Groups data elements under the specified parameter as a record. Typically we use this to provide metadata to the segment. viii. Format - Can be set to None, currency, number or date. ix. Format Value - Provide the conversion standard for the selected format. x. If you need to delete a parameter row, select the parameter row you want to delete and click Delete. This action removes the parameter row from the list of service parameters. 11. Check the result of the output parameter by clicking the Results radio button. It displays the desired element configured in the output parameter. In this example, we got the following output: 12. Click Save icon on the toolbar. Do this for each of the Web Services for the WSDL. 15.13.2.2 Adding a Sync Scope After you define a DataSource for Webservice, you can add a SyncScope using the created data source. When you create a SyncScope, you can create an application from the SyncScope objects and create offline services. Copyright © 2012 Kony, Inc. All rights reserved. Page 546 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 1. Right click SyncScopes and select Add SyncScope. The Add SyncScope dialog appears. 2. Specify any name for the SyncScope. 3. Specify a namespace for the SyncScope. The namespace can be of any format, for example com.kony. 4. Select the appropriate datasource from the drop-down. 5. Select the type of Sync Strategy. For more information about the types of Sync Strategies refer the Kony Sync Framework Getting Started Guide. 6. Set the Change Tracking Policy(CTP) if you want to track the changes happening in the server database. Set CTP as Kony Sync Server, if you want to SyncServer to track the changes. Select Provided by Datasource if you have a provision to track changes in the Datasource. For Database this would be like a timestamp column which updates for any change made to the row. 7. If CTP is provided by Datasource, then select the Change Tracking Columns. Select the Last Updated Timestamp check box when you have column which represents the incremental changes. Select the Soft Delete Flag check box when the database has the column which represents soft deletes. Copyright © 2012 Kony, Inc. All rights reserved. Page 547 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 8. In case of conflicts between the data at the client and server end, specify any of the following: l l l Client Wins: The changes on the client side take precedent over the changes on the server side. Server Wins: The changes on the server side take precedent over the changes on the client side. Custom: Enables you to upload an Interceptor class which comprises the logic or policy for conflict resolution. 9. Conflict Interceptor Class: Enables you to browse and upload an interceptor class which comprises the logic or policy for conflict resolution. For more information about interceptors and the types of interceptors, refer the Kony Sync Framework Getting Started Guide. 10. Click Finish. The created SyncScope appears below the SyncScopes folder. 15.13.3 Adding or Editing the Sync Object In the Sync Configuration View, you can do the following: l Add a SyncObject or a SyncAttribute l Edit a SyncObject 15.13.3.1 Adding a SyncObject In the SyncConfiguration view, after you have added a DataSource and then a SyncScope, add a SyncObject in the existing list of Objects. To do so, 1. Right-click the created SyncScope and select Add Sync Object. 2. Specify the name for the SyncObject. 3. Click Finish. Important: It is mandatory to define a SyncAttribute for any new SyncObject that is created. If you do not do so, an error appears when you generate the application forms or offline services. Copyright © 2012 Kony, Inc. All rights reserved. Page 548 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.13.3.2 Adding a Sync Attribute Every SyncObject created has attributes. For example a SyncObject comprising the summary of a data can have attributes such as month, year, owner of the object 1. Right click the SyncObject and select Add Sync Attribute. 2. Enter a name for the SyncAttribute, the datatype for the attribute, select whether the value can be set to null, the maximum length of the data in the field, select whether the field is an autogenerated field, such as customer id field like 1,2,3 which have counters and are autogenerated, and whether the attribute would be key of the SyncObject table. 3. Click Finish. The added SyncAttribute appears under the SyncObject. Copyright © 2012 Kony, Inc. All rights reserved. Page 549 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.13.3.3 Editing a SyncObject Every SyncObject can have multiple attributes, relationship with other SyncObjects. Editing Attributes To edit attributes that are already part of a SyncObject, do the following: 1. Right click the SyncObject you for which you want to edit the attributes for and select Edit. The Edit SyncObject dialog appears. 2. All the attribute fields that are editable are enabled. You can do any of the following: l l l Name: Name of the attribute in the SyncObject. Each attribute is automatically named when you import a Data Object, you can rename the attributes for a SyncObject using this field. Is Key: You can set the value in this field to true or false . Set this field to true to enable an attribute of an Object to be the key for that particular object. Once you set an attribute as a key its values have to be unique. Type: Specifies the datatype of an attribute. Choose an appropriate datatype for an attribute from the list of available. Copyright © 2012 Kony, Inc. All rights reserved. Page 550 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications l Is Nullable: You can set the value in this field to true or false. Set this field to true to specify whether a certain field can be left blank without any value specified in it. l Max Length: Specifies the maximum number of characters an attribute can have. l Autogenerated: Specifies whether a field is auto generated when you build a project. l Use the Filter field to filter the attributes of an Object and edit the fields accordingly. l You can also add an attribute using the add ( ) button and fill the corresponding fields accordingly. To remove an attribute, select the attribute row or name and click the delete( ) button. You can change the order of the attributes by selecting the attribute and using the up or down arrows. To insert a new attribute before another attribute click after another attribute click . To insert an attribute . 3. Click Finish. Editing Relationships To edit relationships that are already part of a SyncObject or to add a new relationship between SyncObjects, do the following: 1. Right click the SyncObject for which you want to edit the relationships for and select Edit. The Edit SyncObject dialog appears. 2. Select Relationships from the left pane. 3. You can edit the existing relationships between SyncObjects. l Target Object: Target SyncObject to which the current SyncObject creates a relationship with. Click the click OK. l l l l button, to change the Target Object. Select a Target Object from the list and Relationship: Specify the type of relationship between the Source attribute (record) in the SyncObject to the Target attribute(child record) of another SyncObject. Target Attribute: Specifies the attribute of the other SyncObject with which you want to relate your Source Attribute to. Source Attribute: Specify the attribute of the SyncObject you want to link the Target Attribute to. Cascade: Set this value to true or false. Setting this to true implies that when you delete a record in the parent table, it will subsequently delete all the records in the child table as well. 4. You can also add a relationship using the add ( ) button and fill out the corresponding fields accordingly. To remove a relation, select the attribute row or name and click the delete( ) button. You can change the order of the relationships by selecting the relationship and using the up or down arrows. To insert a new relationship before another relationship click another relationship click . To insert a relationship after . Copyright © 2012 Kony, Inc. All rights reserved. Page 551 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 Operation Mapping You can map the operations Create/Update etc. with the corresponding web service which are added under the Datasources. l Create/Update/Delete: These operations are used when an entity is created/updated/deleted by the application. l Get: Used in conflict resolution. l Get Updated/Get Deleted: Used to get the incremental changes from the enterprise to the application. l GetAll: Used in unprovisioned DataSources to get all the data from the enterprise to the application. To map operations do the following: 1. Right click the SyncObject for which you want to edit or create the operations for and select Edit. The Edit SyncObject dialog appears. 2. Select Operations from the left pane. 3. Map the Input parameters. Copyright © 2012 Kony, Inc. All rights reserved. Page 552 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 4. Select the Service Input parameter from the dialog and corresponding source type and source value from the drop-downs. The following are the source types for input parameters: l Attribute: To map the service input parameter from the sync attribute. l Constant: To map the service input parameters to the constant value. l Context: To map the service input parameters from the context variables. l Context: To map the service input parameters from the context variables. l l l l l l l USER_ID: This variable will be set into the context by the sync engine. This variable contains the user id of the user who initiated the sync. LAST_SYNC_TIMESTAMP: This variable will be set into the context by the sync engine. Last updated time stamp will be sent from the device for each sync. Server will send the updated last sync time in the response. This has to be mapped in 'getUpdated' operation to get incremental updates. CURRENT_TIMESTAMP: The current time of the server. If 'getServerTime' is defined in the sync configuration, then this value will contain the datasource current time as returned by the 'getServerTime' service, otherwise value will contain the sync server local current time. MORE_CHANGES_AVAILABLE: This context parameter has to be mapped in the 'getUpdated' operation output mapping for batch processing. If the value is evaluated to true, then 'getBatch' operation will be invoked for the next batch. If this context variable is not mapped, then more changes available will be considered as false. PENDING_BATCHES:This context parameter can be mapped to indicate the pending number of batches. This is an optional parameter, if it is not mapped, then pending batches will be '0' BATCH_SIZE: This is set by the sync engine into the context for the input mapping. Operations like 'getUpdated' and 'getBatch' can map this in the input mapping. Batch size value will be sent from device request. SESSION_ID: This context variable can be set in the custom authentication manager class for session based batches. If SESSION_ID is set in the context, the user will be authenticated in the batch processing only for the first time, subsequent calls just verify whether the SESSION_ID is valid. Once batch processing is over, SESSION_ID is cleared. 5. Select the Service Output parameter from the dialog and corresponding source type and source value from the drop-downs.The following are the source types for output parameters: l l Attribute: To map the service output to the sync attribute. Relationship: To map the service output to the relationship sync object's sync attribute (You can define the relationships in syncobject dialog window). 6. You can also add an operation parameter using the add ( ) button and fill out the corresponding fields accordingly. To remove an operation parameter, select the operation row or name and click the delete( ) button. You can change the order of the operations by selecting the operation and using the up or Copyright © 2012 Kony, Inc. All rights reserved. Page 553 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications down arrows. To insert a new operation before another operation click another operation click . To insert a operation after . 15.14 Using the WebServices in your Application You can import and use the Web Services in your application. For an application you can do the following: l Generating Application Forms. l Generating and using offline services. 15.15 Generate Application Forms With the 5.5 release, the application generation capabilities have been vastly improved. From a SyncConfiguration now you can generate a fully functional offline application within minutes. Given a SyncConfiguration it would generate the following assets: l Application forms : They represent the UX presented to the end user l Model files (part of the modules) : They represent the ORM APIs used for accessing the offline data l Controller files: Act as the glue between the Model and Application forms To generate application forms, 1. Navigate to the SyncConfiguration view. 2. Right-click the Sync icon and select Generate Application Forms. A confirmation message appears if you have already generated a Sync Configuration XML file. Click Yes to override the file and proceed with the application generation. Click No to proceed with the Application generation without overriding the existing file. Copyright © 2012 Kony, Inc. All rights reserved. Page 554 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 3. Click Yes to continue. The following dialog appears. 4. Enter the following: l l l Application Logo: Image for the application logo. Application Splash Screen: Specifies the splash screen image to be displayed. Splash Screen is the initial screen that appears when you launch an application. Application Home Screen Layout: All the forms that are generated are listed on the Home Screen of the application. The forms in the application can appear as follows: List Type Icon Type Copyright © 2012 Kony, Inc. All rights reserved. Page 555 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications l l Application Theme: This field lists themes you can apply to your application. Channels Selected for Application Generation: Select the channels you want to generate the application for. 5. Click Next. The Generate Application Forms dialog appears. 6. Select the Sync objects for which you want to generate forms. Do the following: l To create a form for the Data Object, select any one of the displayed Data Objects in the left pane and click l To remove a Data Object whose form is added, select the Data Object from the right pane and click l . To create forms for all the Data Objects, select any one of the displayed Data Objects in the left pane and click l . . To remove all the Data Object whose forms are added, select the Data Object from the right pane and click . Copyright © 2012 Kony, Inc. All rights reserved. Page 556 of 785 Developing Offline Applications l l l If you click the list. Kony Studio User Guide - 2.1 , then the selected application object in Selected list box will be moved to top of If you click either the up or down arrows, then the selected application object in 'Selected' list box will be moved one level up or down. If you click , then the selected application object in 'Selected' list box will be moved to bottom of the list. 7. Click Next. The Display Configuration tab is selected and the following screen appears. The fields in the Display Configuration tab enable you to set the values for an object (and its fields) you want the end user to view when they traverse a form created for a particular object. 8. Select the Data Object whose display configuration you want to set. 9. Display Name: Set a label for display name of the selected application object. This label appears in the form created for a Data Object. 10. Show in Main Menu: Shows the selected application object in the application main menu. Selected by default. Copyright © 2012 Kony, Inc. All rights reserved. Page 557 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 11. Object Icon: Choose the Icon which will be displayed for the application object in List view or icon view. This icon must be in the .png format. 12. Layout Type: Set the layout type for the fields of a selected Data Object. Based on the layout type selected the fields are displayed as follows: List Screen with Search Bar List Screen without Search Bar Grid View 13. In the Display Properties Area, do the following: l l Field Id: Specifies the field id for a field of a Data Object. Display Name: Specifies the display name for a field. You can change the field name to a user friendly name. l Select the fields that are to be displayed in specific views. l Specify the datatype for each field in the Field Type Column. l l l l In the Validations column, click a field for which you want to add a validation. Specify a validation for a field. For example, if the user is supposed to enter only fifty characters for a field, write an appropriate validation code for the same. If you click , then the selected field will be moved to top of the list. If you click either the up or down arrows, then the selected field will be moved one level up or down. If you click , then the selected field will be moved to bottom of the list. 14. Using the Actions tab you can , do the following: l l Select the Data Object whose Action configurations you want to set. Select the corresponding checkboxes that allow you to select the create, update, delete and display relationships actions for the selected application objects. Note: After you set the configuration for one data object, you can select another data object and set the configurations. Copyright © 2012 Kony, Inc. All rights reserved. Page 558 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15. Click Finish. An application is created. You can view all the forms created for your Data Objects under Application Name> forms> mobile. JavaScript Controller modules are generated under the modules folder which comprises information and the logic for creation, retrieval, and modification about a Data Object instance and its fields. Build the application and view the subsequent forms. 15.16 Generating Offline Services Offline Services provide an API to access data within the Sky DataObjects, Database Tables, and WebServices or the Kony Sync device database depending upon the DataSource. These services differ from the regular services defined using the Service definition editor in the following ways: 1) Offline Services need not be deployed to a Kony Server 2) Most of the Offline Services are available even when the Device offline. When the developer uses "Generate the Offline Services" option from the SyncConfiguration View, Model files are generated within the module folder of the application. These Model Files provide ORM APIs to access the underlying data. You can generate offline services for Data Objects in an application. Using these offline services you can invoke ORM APIs using the Mapping Editor. To generate an offline service, do the following: 1. Navigate to the SyncConfiguration view. 2. Right-click the Sync icon and select Generate Offline Services. A confirmation message appears if you have already generated a Sync modules. Copyright © 2012 Kony, Inc. All rights reserved. Page 559 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 3. Click Yes to override the existing modules and proceed with the offline services generation. Click No to proceed with the offline services generation without overriding the existing file. All the offline services that are generated are listed under your application. When you expand each offline service generated for a Data Object, you can view the methods associated with each Data Object of that Service. Copyright © 2012 Kony, Inc. All rights reserved. Page 560 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 15.16.1 Using the Offline Services in your application You can leverage the create, update, delete, and other operations of a Data Objects in your application. To demonstrate how to do so, we have a sample application which has been created using the procedures stated above. 15.16.1.1 Invoking an Offline Service using the Mapping Editor You can invoke an offline service on a button click or populate data in a segment or within a label using the Mapping Editor. To invoke an offline service using the mapping editor, do the following: 1. Open Event Editor. 2. Right-click Action Sequence and select Invoke Offline Service (Asynchronous). 3. Select a service from the drop-down list or click below: to open Select Service window as shown Copyright © 2012 Kony, Inc. All rights reserved. Page 561 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 i. Select a service from the list available. ii. When you type few letters of a service under Search, all the service names that begin with the characters entered are listed. iii. Select a service from the list and click OK. 4. Click Open Mapping Editor. The Mapping Editor opens. 5. Map the service parameters to variables, data store keys, or widgets on the form from which the service was invoked. 6. Click Finish on the Mapping Editor. An action sequence is defined for invoking a synchronous service. 15.16.1.2 Invoking an Offline Service using an ORM API: As an example we will consider a form whose contents you want to delete on the onclick of a button. To do so, define an onClick function for that button. A sample function defined on an onClick event for a button is as follows: Copyright © 2012 Kony, Inc. All rights reserved. Page 562 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 //Object level ORMs products = new com.kony.sync.Products(); products.productId = 3; product.name = "sample Product"; // Define a successcallback that will be invoked when the object instance is created in the local database function successcallback() { alert("Product created successfully") } // Define a errorcallback that will be invoked incase there is an error creating a instance in the local database function errorcallback (res) { alert("Some problem occurred while creating Product. Code=" + res.errorCode + " Error Message=" + res.errorMessage + " Error Info=" + JSON.stringify(res.errorInfo) ); } //Create a new instance product.create(successcallback, errorcallback); 15.17 Configuring Interceptors The Interceptor interface provides callbacks capability from the Sync Framework to the application, allowing the application to inspect and/or manipulate properties of a sync object before it is inserted, updated, deleted or loaded. Interceptors can execute code before and after an Action (Upload, Download, and Merge) is invoked. Interceptor classes contain methods that are invoked in conjunction with the methods or life cycle events of the sync services. For more information about interceptors, refer the Kony Sync Framework Getting Started Guide. Copyright © 2012 Kony, Inc. All rights reserved. Page 563 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 1. Right-click the Sync icon and select Configure Interceptors. 2. Add the jar files which have the Interceptor implementation classes (You need to create the jar file from the interceptor implementation separately). To add the jar file, click in the left pane. 3. Click to add the Interceptor row. Select the Interceptor type from the drop down, and select the Interceptor class look-up. 4. Select the interceptor implementation from the list and click OK to add the interceptor. 5. Click Finish to save the interceptors in sync configuration. 15.18 Loading an Existing SyncConfiguration File A SyncConfiguration file you have created for an application can be copied to another application. This reduces the effort for creating a SyncConfiguration with datasources and SyncScope from scratch. A SyncConfiguration file for an existing project is copied at <<Workspace location>>\<<Appname>>\sync\<<filename.xml>>. You can also open an existing SyncConfiguration file when you click in the SyncConfiguration view and select Open Sync Folder. Copyright © 2012 Kony, Inc. All rights reserved. Page 564 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 1. Right-click the Sync configuration view and select the Load Sync Configuration option. 2. Select the Sync Configuration file which you wanted load in the project. 3. Click Finish to load the sync configuration. 15.19 Kony Sync Server Planning Guidelines You need to decide how you want to install and configure it to provide the best possible performance before you develop an application that accesses Kony Sync server. The installation and configuration choices that produce the best performance depend on your reporting requirements, resources, and preferences. Below are the typical installations for a Development, Quality Assurance (QA) and Production environments. 15.19.1 Standard Development Environment Setup Install all components on one computer only for a single developer or proof of concept or in demonstration environments where the user load is small. In this setup both the Database and Sync Server are installed on the same computer. Operating System Specification Windows Windows Server 2008 / Windows 8 Professional / Windows 7 Professional, 64 bit, 4 Cores Linux Red Hat Linux Enterprise 6.0, 64 bit, 4 Cores Recommended RAM 8 GB or more Note: Refer to Kony Sync 5.0 Release Notes or Kony Sync 5.5 Release Notes to check any compatible RDMS other than MS-SQL 2008 Enterprise Server that Kony Sync supports. 15.19.2 Standard QA or Certification Environment Setup A QA environment represents a very close replica of the actual production environment setup except that the number of server instances and the capacity of each of the instances are lesser than those in Production Environment setup. In this setup, Kony Sync Server and the Database are installed on separate computers. Note: The below figure indicates that the Secure Socket Layer (SSL) termination that happens at the load balancer level. This is a recommended setup for the Kony Sync server installation. If the Enterprise policies mandate that SSL terminates at individual Tomcat / Application server instance, then you need to setup SSL certificate accordingly for each server. Copyright © 2012 Kony, Inc. All rights reserved. Page 565 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications Operating System Specification Windows Windows Server 2008 / Windows 8 Professional / Windows 7 Professional, 64 bit, 4 Cores Linux Red Hat Linux Enterprise 6.0, 64 bit, 4 Cores Recommended RAM 16 GB or more 15.19.3 Standard Production Environment Setup A production environment represents the setup that live / actual users access. The capacity of the servers is definitely much more than Development or QA setup. The number of instances also vary or may be more, depending upon the number of concurrent users the system plans to support. Note: The below figure indicates that the Secure Socket Layer (SSL) terminates at the load balancer level. This is a recommended setup for the Kony Sync server installation. If the Enterprise policies mandate that SSL terminates at individual Tomcat / Application server instance, then you need to setup SSL certificate accordingly for each server. Copyright © 2012 Kony, Inc. All rights reserved. Page 566 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications Operating System Specification Windows Windows Server 2008 / Windows 8 Professional / Windows 7 Professional, 64 bit, 4 Cores Linux Red Hat Linux Enterprise 6.0, 64 bit, 4 Cores Recommended RAM 8 GB or more 15.19.4 Plan Kony Sync Server Capacity Planning for capacity means determining the hardware that you need for your system to perform well under its anticipated workload. Planning capacity is a challenge. It involves many variables, some of which are difficult or impossible to measure. It is the science of measuring known variables and developing an educated estimate of resource requirements based on those measurements. It is also an art of allowing unknown variables and assessing their impact on the estimates derived from the known variables. To determine requirements for your Kony Sync Server capacity, gather information about the following: l Number of users accessing Kony Sync application from their devices l Application complexity l Deployment infrastructure Planning capacity is an on-going process. After deploying Kony Sync Server, monitor and modify your capacity as necessary to meet your performance expectations. Copyright © 2012 Kony, Inc. All rights reserved. Page 567 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.19.4.1 Estimate User Load of Kony Sync Server Estimate the user load Kony Sync server is expected to handle. In general, the greater the number of users and the more concentrated their requests are over time, you need more hardware for a system to perform effectively. As a result, when planning adequate capacity for Kony Sync Server, you should estimate the number of people who would use Kony Sync Server and determine when they would use Sync the application. This helps you decide not only how much hardware you need, but also how to make the best use of the hardware you have. The only users who load the Kony Sync Server are those who actually perform the processing. These are concurrent users. You can estimate the number of concurrent users, based on your total user population, by distinguishing between named, active, and concurrent users. a. Named users: Named users are all the users authorized to use Kony Sync application; your total user population. b. Active users: Active users are a subset of named users. Active users can log on to Kony Sync Server and can demand system resources. c. Concurrent users: Concurrent users are a subset of active users. Concurrent users demand system resources, for example: submit requests and wait for response to requests. As a general rule, the ratio of named to active to concurrent users for business applications should be 100:10:1. In other words, for every 1000 named users, there are 100 active users and 10 concurrent users. The concurrence ratio can vary over time, and is affected by many factors. For example; the number of concurrent users relative to active and named users tends to be higher when the user population is small. The most important determinant of the concurrence ratio is how processing demand is distributed over time. 15.19.4.2 Assess Complexity of an Application Load is determined by the number of concurrent users also by the complexity of their processing requests. The greater the complexity of a request, the more time is needed to process the request. In general, hardware resources can process more requests in a given time period when the requests are simple rather than complex. As a result, application complexity is an important determinant of the number of concurrent users that can be supported on a given hardware infrastructure. The complexity of a Kony Sync application depends on the amount of work required to process the result set returned from the database query or the amount of time required to get response from an external Web Service. You can improve performance during peak times by identifying queries run at peak times and improving their efficiency while meeting user requirements. As query patterns change over time, assessing application complexity and improving reporting efficiency should be on-going activities. 15.19.4.3 Deployment Infrastructure Use true server computers than fast workstations. True server computers run business applications faster and provide systems that are less likely to fail. Copyright © 2012 Kony, Inc. All rights reserved. Page 568 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications Are web and application servers dedicated solely to Kony Sync Server for or shared by other software products? If other applications share the resources, you should consider these applications when you determine capacity requirements. The complexity of your security infrastructure can increase response time. As your security infrastructure becomes more complex, a user request must be validated more frequently. For example, if you implement multiple network firewalls, each firewall must validate every request that passes through it. This can increase the time taken to complete the request. In addition, if you use Secure Socket Layer (SSL), the overhead of SSL encryption adds both processing overhead and size to the response. 15.19.4.4 Kony Sync Performance Benchmarks Application Scenario SyncStrategy Datasource Total Number of Rows Average Batchsize (in MB) Configuration OTA Sync Salesforce WebService (XML based) 3500 approximately 1.5 MB Operating System Windows Hardware Specification Configuration Windows Server 2008 R2 Standard Core 2 Duo CPU, 3.05 GHz, 64 bit OS, 4 GM RAM Java JDK JVM Heap Size Application Server Configuration Oracle JDK 1.6.0_26 1 GB Tomcat 7 SyncConsole Database MSSQL Server 2008 Number of Sync Server Instances 1 Maximum Number of Concurrent Users 120 (before system performance degraded) Average response time to download approximately 40 seconds approximately 1.5 MB packet Total time for initial download approximately 4 minutes You can use the above benchmarks to estimate the value of number or servers / instances required for a supporting larger number of users and expected system performance. 15.19.5 Monitor and Tune Kony Sync Server Performance Kony Sync Server deployment environment changes over time. User populations grow, processing requests tend to increase in number and complexity, and network capacity and other aspects of infrastructure may be modified. These changes can affect Kony Sync Server performance. As a result, it is important to monitor and tune performance regularly. Monitoring performance means checking status of your Kony Sync Server and its resources regularly. Kony Sync Server provides metrics for checking the performance of the system and services. Copyright © 2012 Kony, Inc. All rights reserved. Page 569 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 Kony Sync Console provides a view of the requests that the server received and time it took to execute those requests. These requests are either for downloading the delta dataset or for uploading changes from device to the enterprise datasource. Tuning can involve adjustments in the following areas: l l Kony Sync Server: Adjust your application server memory and connection settings as required for better performance. Databases: Keep your databases optimized for querying and reporting. 15.19.5.1 Tune Kony Sync Server Installation l Enable GZIP Compression Compression is a simple, effective way to save bandwidth and speed up the bulk download response times. Simply put gzip compression works by finding similar strings within a text file, and replacing those strings temporarily to make the overall file size smaller. This form of compression is particularly well-suited for the Kony Sync responses. Copyright © 2012 Kony, Inc. All rights reserved. Page 570 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 To ensure that GZIP compression is turned for Tomcat make sure you see similar tag in <TOMCAT_ INSTALL_DIR>\conf\server.xml. <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" compression="on" compressionMinSize="512" noCompressionUserAgents="gozilla, traviata compressableMimeType="text/html,text/xml,text/css,text/plain,te xt/javascript,application/xjavascript,application/javascript,application/json,application/ xml"/> For other application servers please refer to the Server Configuration/Administration Guide for enabling GZIP compression. l Disable DEBUG logging in Production Environments A debug log records database operations, system processes and errors that occur when executing a transaction during development lifecycle. The system generates a debug log for a user every time that user executes requests for an upload or download operation (or even device registration). Debug logs slow down the application performance as the server spends a lot of time performing the input and output (I/O) operations to capture the LOG statements. In a production environment, the user is typically interested to know only runtime errors and do not need a complete log trace for every user. Ensure that below logger is set to ERROR in log4j.properties file. For Kony Sync 5.0.X, the log4j.properties file is located at: <sync.home>/apache-tomcat-7.0.26/webapps/syncconsole/WEBINF/classes/log4j.properties <sync.home>/ apache-tomcat-7.0.26/webapps/syncservice/WEBINF/classes/log4j.properties For Kony Sync 5.5.X, the log4j.properties file is located at: <sync.home>/conf/console-log4j.properties <sync.home>/conf/services-log4j.properties Note: Once you modify the log4j properties file, you need to remove syncconsole.war and syncservice.war from webapps folder, otherwise it gets overridden again on tomcat start. Copyright © 2012 Kony, Inc. All rights reserved. Page 571 of 785 Developing Offline Applications l Kony Studio User Guide - 2.1 Disable Trace Logs in Production Environments Tracelogs enable the administrator to view incoming HTTP requests and responses. This is very useful to debug issues during development. It impacts the application server performance. So unless you debug an issue, you should turn off the Tracelogs. To turn off the trace logs follow these steps: 1. Log on to Kony Sync Management Console. 2. Click Config section. 3. Clear Enable Trace Logging checkbox (the action is auto saved) as below: 15.19.5.2 Tune Database Kony Sync implementation uses a relation database (Microsoft SQL Server or Oracle) to store user information and log performance metrics. To ensure that Kony Sync implementation continues to perform well, it is important to maintain the performance of your database. This means optimizing it for querying, reporting, and analyzing. If Kony Sync and other applications demand more of a database than it can provide, or if queries are too large for a database to handle efficiently, you may experience increased response times and degradation in Kony Sync performance and scalability. For information about tuning your database, see its documentation. 15.20 Kony Sync Application Design Guidelines While designing the SyncScopes and SyncObjects the developer should ensure that SyncObject model represents what the application needs and is not a blind replica of the Enterprise Backend model. Do not define that attributes that you never use in the application as part of the SyncObjects. Define only those Tables or Business Objects in the SyncConfiguration that you actually use in the application. You should make the objects that share similar datasource and similar synchronization characteristics as part of the same SyncScope. Synchronization characteristics include how frequently the data changes on the device as well as on the backend. Copyright © 2012 Kony, Inc. All rights reserved. Page 572 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 15.20.1 Identifying an Appropriate SyncStrategy Deciding upon a SyncStrategy is one of the key architectural / designs decisions that you need to be make while developing any enterprise grade offline application. This is not a simple decision. It is based on a number of input parameters and system constraints. The following are some of the recommendations that can help you determine how to choose an appropriate strategy: 15.20.1.1 OTASync Strategy OTASync Strategy is a recommended solution when: l l l l l Enterprise backend is highly available to the KonySync Server There is a need to keep the system and operational costs down by not replicating the enterprise backend on the KonySync server The Enterprise backend is "Provisioned". Provisioned means that typical database design patterns are followed, for Example; tracking deletes through a soft delete flag and tracking lastupdated timestamp for each data item (or a table row). These elements are essential for OTASync as they are needed for sending appropriate updates back to the client database and keep the processing as low as possible on the KonySync server The Enterprise backend can provide delta changes based on the last updated timestamp that the devices sends Every time the users perform sync, then it is essential that they get access to the Latest updates on the Enterprise backend. 15.20.1.2 PersistentSync PersistentSync is a recommended solution when: l l l l The Enterprise backend is not highly available. A scheduled system down time does not allow users to access the Enterprise backend (typically due to time zone differences) The Enterprise backend is "UnProvisioned". Provisioned is term used for signifying that typical database design patterns are followed, for Example; tracking deletes through a soft delete flag and tracking lastupdated timestamp for each data item (or a table row). An UnProvisioned backend does not follow these characteristics. It is acceptable that users are productive even with an information set that is "outdated" or "stale" by a few hours. 15.20.2 Use Client Filters You may use Client Filters to ensure that the data downloaded to the device is optimized for the user. Copyright © 2012 Kony, Inc. All rights reserved. Page 573 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 Every user often deals with a few thousands of records while the Enterprise backend stores millions of records across all the users. In such a scenario it is important the every device has only the data the user is interested in. Client Filters enable the sync server to filter data specific to the user before sending the response. For Database datasource, these filters form the part of the WHERE clauses and UNION queries when selecting the data for each table. For other data sources these are passed as input params to the Services Endpoints. 15.20.3 Avoid Complex Relationships between SyncObjects While defining a SyncObject model, relationships form an essential part of the definition. The user must be very careful in not replicating every relationship between the objects. You should define only those relationships in SyncConfiguration that drive the application behavior. Relationships defined in the SyncConfiguration drive the primary key management done on the server as well as the data filtering when downloading data to the device. Consider the below two database tables and the relationship between them. It is clear that the StatusLookup table provides more descriptive information about a particular application status. Even though Application has reference to a key in StatusLookup, it may not be necessary to download only those StatusLookup rows as referenced by the Application. Even though this is desirable it can be over optimization. Application and StatusLookup share the parent child relationship in a real world context. So in this, defining a relationship between these two SyncObjects is overkill. 15.20.4 Differentiate between Lookup and Transactional Data Almost in every Enterprise backend system, there is lookup (Reference) data that changes very rarely (mostly READ) while there is transactional data that changes very frequently (mostly WRITE). By designing them as part of different SyncScopes, you can apply different synchronization characteristics. You can synchronize Lookup data every two days while you can refresh the transactional data every two hours. Lookup data is often same across users, hence it may be the candidate for applying client filters. 15.20.5 Identify Appropriate Batch Size for the Application When downloading data to the device, the SyncServer does not send all the data in one response. It sends them in batches. The user defines the batchsize while initiating a sync (default batchsize is 500). Copyright © 2012 Kony, Inc. All rights reserved. Page 574 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 A very small value of batchsize results in many network calls and hence can lead to poor sync performance. A very large value of batchsize can lead to Out Of Memory issues on the server and the device (as all the data in batch is loaded in memory). You are recommended to perform some tests (using different batchsizes) with real world application data to arrive at the batchsize that is more appropriate for the application. 15.20.6 Getting the SyncObject Relationships Right You need to get the SynObject relationships right for Database Datasource. Kony Sync currently supports One-To-Many and Many-To-One relationships between the SyncObjects. It is important to understand how the developer should decide which side of the relationship is the Many side. The below example illustrates how to identify that. The Many side is always defined on the table that has the Foreign Keys. Example 1 In the above example, since the Foreign keys exist on the Person table it becomes the Many side of the One-To-Many or Many-To-One relationship. Example 2 In the above example, since the Foreign keys exist on the Address table it becomes the Many side of the One-To-Many or Many-To-One relationship. It is equally important to identify where to define this relationship. Let us say in Example 1, we can define the Many-To-One relationship on the Person SyncObject or One-To-Many relationship on the Address SyncObject. The relationship should be defined on the SyncObject whose filters have to be inherited by the other Syncobject. For example; if the application demands that only selected PersonIDs that the user defined should be downloaded (so a client filter on Person) and only those Address records that the client filter selected, need to be downloaded, then you have to define the relationship on the Person SyncObject. (As in this case Address inherits the filter criteria from Person). Copyright © 2012 Kony, Inc. All rights reserved. Page 575 of 785 Kony Studio User Guide - 2.1 Developing Offline Applications 15.20.7 Define Appropriate Indexes Ensure that appropriate indexes are defined for all the Columns that are part of the relationship and client filter criteria. Note: Indexes can affect the WRITE performance on the tables. 15.20.8 CRUD Friendly WebService Design Kony Sync framework operates on SyncObjects. To read/update data held in these objects, it expects the Enterprise backend to provide a CRUD friendly interface. This helps the Sync Framework to map actions performed on the data to be replicated on the Enterprise backend. The WebServices should define the below operations for each object. Operation Create Update Delete Get GetUpdated GetBatch GetServerTime Description Service that takes all the filed level data in the request and creates an instance in the enterprise data source and returns the auto generated primary key information in response (if primary key is auto generated). Service that takes all the field level data along with primary key in the request and updates the instance in enterprise data source. Service that takes the primary key of the row and deletes the row from the data source. Service that takes the primary key of the row in the input and gives all the field data in the response. This service is typically used for doing conflict resolution. This is also invoked when GetUpdated returns only primary keys and does not return all the data values for a SyncObject. Services that takes the date time value in the request and returns all the rows (with all the field data) changed after that date time. Service that provides ability to retrieve data in batches. This is defined once at datasource level. It returns current datetime value of the datasource. It is not mandatory to define this service, but you are recommended to have this service to ensure that a very precise batching is done for large datasets. So consider this while designing the services. Note: There is no restriction on the name of the WebService methods but the semantics / behaviour has to be similar to what is described above. 15.20.9 Optimize the SOAP Requests Salesforce offers a very rich query interface through its WebService interface. This API allows a user to define its own objects as well as construct complex queries to select only the required fields. With respect to SFDC, one must avoid downloading deleted records to the device when downloading data for the initial downloads. You can do this by having a code snippet similar to below, in the SOAP request template for getAll operation mapping. Copyright © 2012 Kony, Inc. All rights reserved. Page 576 of 785 Developing Offline Applications Kony Studio User Guide - 2.1 <urn:queryString>select Id, IsDeleted, MasterRecordId, Name, Type, RecordTypeId, LastModifiedDate from Account where LastModifiedDate&gt;$StartDate and LastModifiedDate&lt;$EndDate #if ($InitialSync=='true') and IsDeleted=false #end</urn:queryString> SFDC expects a specific NULL tag to set the value of an attribute to null. So one must modify the update and create SOAP request template in the operation mapping. #if($Name != "null") <urn1:Name>$Name</urn1:Name> #else <urn1:fieldsToNull>Name</urn1:fieldsToNull> #end Copyright © 2012 Kony, Inc. All rights reserved. Page 577 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool 16. Working with Scraper Tool The process of extracting content from a remote web page is known as HTML Scraping. Scraper Tool is used to scrape data from an external web page. The data extracted with the Scraper is available to the Mobile Application as it would be if it were coming from a web service or other data connection type. The data extracted from any web page is used within a Mobile Application. Scraper Tool performs the following steps while extracting data from an external web page: 1. Establishes a connection with an existing web page 2. Extracts content from the HTML page 3. Extracts data from the source of the HTML page using HTML tags (XPath) and/or regular expressions. XPath - a query language for selecting nodes from an XML document. The following table lists the commonly used XPath expressions: Regular Expression nodename / // . .. @ Explanation Use this expression to select all child nodes of the specified nodename Use this expression to select all the elements from the root node Use this expression to select the nodes that match the selection Use this expression to select the current node Use this expression to select the parent of the current node Use this expression to select the attributes within a node For more information about using XPath, see http://www.w3schools.com/xpath/. Regular Expression - a regular expression, also referred to as regex or regexp, provides a concise and flexible means for matching strings of text, such as particular characters, words, or patterns of characters. For more information about regular expressions, see http://www.regular-expressions.info/tutorial.html. 16.1 Use Case Scenarios Scraper Tool is useful in the following scenarios: l l l when no web services are available as an alternative when there is a business logic embedded in the web page; scraping fetches the data after the business logic is executed so that the logic on the client-side is minimized even if there are web services available to scrape other web sites in conjunction with an application. For example, a hotel application might want to extract data from a third-party partner site (a restaurant for example) l when you want to extract data from a web page l when you want to pass the extracted data from a web page to another service call Copyright © 2012 Kony, Inc. All rights reserved. Page 578 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool l when you want to monitor a website constantly and extract some information at regular intervals or trigger an action based on a change. For example, polling a newspaper site to extract news items and display on a gadget. For more information about the Prerequisites, see Prerequisites for Using Scraper Tool. 16.2 Prerequisites for Using Scraper Tool Before you can start using the Scraper Tool, you have to make sure that the following prerequisites are met: l Install a Third-party Tool that Examines the Web Pages l Configure the middleware.home path l Create the .properties file l Configure Proxy Settings l Create DSL File(s) 16.2.1 Install a Third-party Tool that Examines the Web Pages To use the Scraper Tool, you have to decide upon the web page(s) you want to scrape to extract the relevant data. Once you have decided on the web page, you have to examine the web page to understand the header information, the HTML tags in the web page, and the response the web page gives. To examine the web page, there are third-party tools available for each web browser as shown below: Web Browser Mozilla FireFox Microsoft Internet Explorer Google Chrome Opera Third-party Tool Firebug IE WebDeveloper/IE Inspect/Firebug Lite Firebug/Firebug Lite Firebug Lite In the example explained in this document, we will use Mozilla FireFox as the web browser and Firebug as the third-party tool to inspect the web pages. On any web page that is open in Mozilla FireFox, click Firebug. at the bottom-left corner of the browser to activate 16.2.2 Configure the middleware.home path You need to perform this step so that you can test the response of the Scraper Tool on the computer. 1. Go to Eclipse installation folder. 2. Open eclipse.ini configuration file. 3. Add the middleware.home path in this configuration file as shown below: -Dmiddleware.home=<workspace location> Copyright © 2012 Kony, Inc. All rights reserved. Page 579 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 Note: This path is known as the middleware home. This path should always point to your workspace. 4. Create a folder genericscrapper in the <middleware home> folder. In this case, the path will be <middleware home>/genericscrapper . Note: This folder is known as the scraper home. Note: The purpose of the above step is to indicate to Kony Studio to look for the DSL and the properties files related to the application in the <scraper home> folder. 16.2.3 Create the .properties file The properties file has all the configuration parameters/variables (defined at the application level) that are required for the Scraper Tool. There is a DEBUG parameter that logs errors in the Scraper Tool. l DEBUG=ERROR Logs Runtime Exceptions and Errors l DEBUG=ALL Logs all Exceptions/Errors related to input/output parameters including the time at which the service call was made l DEBUG=0 Disables logging. The Scraper Tool uses two Java Libraries to connect to the Kony Application Server. You specify the connection type to be used by the Scraper Tool in the properties file using the connlib configuration parameter. The connlib parameter is used to change the connection type: l connlib = httpclient uses httpclient Java Library to connect to the server. If you do not specify the connlib configuration parameter in the properties files, httpclient is considered as the default connection type. l connlib = urlconnection uses urlconnection Java Library to connect to the server. The following is a sample properties file: DEBUG = ALL # This indicates the level of debug that we want to define for the Scraper Tool. This configuration parameter can take the values ALL, ERROR, or 0. DOMAIN_NAME = <url to be scraped> Copyright © 2012 Kony, Inc. All rights reserved. Page 580 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool # DOMAIN_NAME is the name of the variable that captures the fixed URL that needs to be scraped. If you are using the same domain name with different sub-domains for different services, you can define the domain name in a variable in the properties file, so that it is used by all the DSL files. For example, if you want to scrape http://www.yahoo.com/news for one service and http://www.yahoo.com/weather for another service, in either case as the domain name is constant, you can define that in the properties file as DOMAIN_NAME=http://www.yahoo.com The value of this variable is picked up by the propkeyname parameter in the DSL file. This parameter can be named anything but that needs to the same in both the properties files and the DSL files. connlib = urlconnection # httpclient is the default connection type. Use this configuration parameter if you want to explicitly change the connection type to urlconnection. To create a properties file, follow these steps: 1. Go to <scraper home> folder. 2. Create a folder with the name <appID> . Replace <appID > with the actual Application ID. 3. Create a file with the name <appID>.properties in the folder created in above step. 16.2.4 Configure Proxy Settings Scraper Tool provides you with the option to configure proxy settings. Configuring the proxy settings enables you to connect to the Java Services from computer through a proxy server in between. To configure proxy settings, follow these steps: 1. Open the <applicationName>.properties file. 2. Add the following parameters in the properties file: http.proxyhost = <proxy host site> http.proxyport = <port number> (default port is 80) 3. Add the following parameters for authentication support: http.proxyuser = <username> http.proxypassword = <password> These parameters in the properties file enable the authentication to the proxy server. Copyright © 2012 Kony, Inc. All rights reserved. Page 581 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 16.2.5 Create DSL File (s) DSL stands for Domain Specific Language. The DSL File is an input to the Scraper Tool. For every Java Service that uses the Scraper Tool, there should be a corresponding DSL file created at the following location: <scraper home>/<appID>. Any DSL file consists of two sections: l Input Parameters o l This section contains all the input parameters that need to be passed to the Scraper Tool. url is an important input parameter, which specifies the URL of the web page that needs to be scraped to extract the required information. For more information about other input parameters, see Input Parameters. Output Parameters o This section contains all the output parameters that capture the data scraped by the service from the specified URL. For every piece of information you want to extract from the web page, you need to define a corresponding output parameter and an XPath or a RegEx to extract the data. For information about all the output parameters, see Output Parameters. Note: The input and output sections should be separated by ----- (5 dash characters). Note: Prefix any line with the # character to comment out that line. To create DSL files within the IDE, follow these steps: 1. Make sure that you have downloaded the plug-ins mentioned in the Scraper View section. 2. Expand the services -> scraper folder in the Applications View. 3. Right-click DSL and select New DSL Module. 4. Enter a Module Name and click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 582 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool 5. The DSL file opens in the editor pane as shown below: Populate the required input and output parameters in the DSL file and save it. Note: Insert a blank line after all the statements. 16.3 Input Parameters This section explains the various input parameters that you may need to use in a DSL file for the Scraper Tool: propkeyname This parameter is used to specify configuration parameters of a web page like domain name, time out, etc. If you specify the fixed URL (domain name), this value is retrieved from .properties file. This value is replaced in URL. This variable is used when you have different services that use different subdomains of the same URL. In such a case, it is beneficial to define the main domain name as a variable in the properties file. The sub-domains for various services can be defined in the corresponding DSL files. Note: The properties file is saved as <appID>.properties at the same location as that of the DSL files. Syntax propkeyname `<variablename> Parameter variablename Description used as key to retrieve variable value from .properties file Example DSL file content to scrape data: propkeyname `DOMAIN NAME url `DOMAIN NAME/index.html `get The DOMAIN_NAME variable is retrieved from the properties file. If the variable DOMAIN_NAME is defined as http://www.example.com, then the URL that will be scraped will be http://www.example.com/index.html. Copyright © 2012 Kony, Inc. All rights reserved. Page 583 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool repurlparam This parameter specifies the part of the URL that needs to be appended to the URL parameter in the DSL file. If the input to the URL is being passed dynamically, you can define that input in the repurlparam. Note: You must pass the repurlparam parameter as part of postdata in the code. Syntax repurlparam `<variablename> Note: propkeyname and repurlparam have similar functionality. propkeyname is used for static values and repurlparam is used for dynamic values. Parameter variablename Description will be replaced if exact text appears in url string For example, if you want to scrape http://www.finance.yahoo.com to get the stock quote of any company you enter dynamically, that company name is defined as a variable with repurlparam. This variable is replaced in the actual URL. Example DSL file content to scrape data: propkeyname `DOMAIN_NAME repurlparam `dynamic_url url `DOMAIN_NAME/dynamic_url `get Note: Scraper tool will replace the variables propkeyname and repurlparam with their actual values in url parameter before connecting to the specified page using the URL string. url This parameter specifies the URL of the web page from which you are going to scrape the data. Syntax url `<address> `calltype `mr `encode Parameter address calltype Description has URL address of the page or a combination of propkeyname and repurlparam variables specifies the type of call, get or post use get as the calltype when you do not need pass any input parameters to the Scraper Tool Copyright © 2012 Kony, Inc. All rights reserved. Page 584 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Parameter Description mr Note: Use this parameter only when manual redirection is required. encode This is an optional parameter. Use this parameter to indicate to the Scraper Tool that there is redirection happening on the specified URL (for HTTP response code 300+). This is an optional parameter. Use this parameter when you want to encode the URL and pass the encoded URL to the Scraper Tool. mr parameter is used when you know there is a manual redirection happening in the URL you are trying to scrape. For example, when you enter the URL http://www.google.com, depending on your location the browser will redirect to the corresponding Google web page, i.e., http://.www.google.co.in if you are in India. When you examine the URL that you want to scrape, if there is a redirection involved, the Status of the received response would be 300 or above. The Location parameter in the Header indicates the web page to which the redirection happens. If there is redirection happening on the web page and you do not specify mr in the corresponding DSL file, response is fetched from the URL that is scraped, which is incomplete. If mr is specified in the url parameter in the DSL file, the response is fetched from the redirected page as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 585 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Example DSL file content to scrape data: a url url url url url url a `http://www.example.com `http://www.example.com `http://www.example.com `http://www.example.com `http://www.example.com `http://www.example.com `get `mr `post `mr `get `mr `enocode `get `enocode `post `mr `enocode `post `enocode mr indicates manual redirection postparam This parameter is used to define the input parameters that you need to pass to the Scraper Tool. This parameter accepts both single and two argument statements. Single Argument Syntax postparam `<parameter> Parameter parameter Description name of the input parameter that you are passing to the Scraper Tool (value of name attribute of param tag in Service Definition file). This name should match with the actual field name on the web page Example HTML: <input type = "text" name = "origin" id = "airOrigin" class ="locationInput" value="MIA" /> Copyright © 2012 Kony, Inc. All rights reserved. Page 586 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Service Definition: <param targetdatatype = "" target="" src ="request" sms-name="" order= "" name = "origin" formatvalue= "" format = "" datatype="string"/> DSL file content to scrape data: postparam `origin Two Arguments Syntax postparam `<parameter1> `<parameter2> for two argument statement Parameter parameter1 parameter2 Description use this parameter if there is an alias name defined for the original field. This parameter is the same as that of the parameter in single argument. name of the input parameter that you are passing to the Scraper Tool Note: If you want to pass hidden values, the parameter name should end with _hiddenjson. Example HTML: <input type = "text" name = "origin" id = "airOrigin" class ="locationInput" value="MIA"/> Service Definition: <param targetdatatype = "" target="" src ="request" sms-name="" order= "" name = "origin" formatvalue= "" format = "" datatype="string" /> DSL file content to scrape data: postparam `alias_name `origin postparam `search_hiddenjson headerparam This parameter specifies the header information like cookie, user-agent etc, along with a HTTP request. Syntax headerparam `<parametername> Parameter parametername Description value of attribute of param tag in Service Definition file Copyright © 2012 Kony, Inc. All rights reserved. Page 587 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Example DSL file content to scrape data: headerparam `example_cookie headerparam `Cookie headerparam `User-Agent User-Agent is a keyword and should be used exactly the same as it is specified here. For information about all the possible user agents that you can use, see http://www.user-agents.org/. Note: When you want to pass cookie using headerparam, its parameter name should be Cookie or any string with _cookie as suffix. optionalpostparam This parameter is used to specify the input parameters that: l are optional l have a specific static value l do not have a value. Two Arguments Syntax optionalpostparam `<parameter> ` ignore | "" | ''|<staticvalue> Parameter parameter staticvalue ignore Description name of the parameter static value of the field used when you want to pass optionalpostparam values dynamically. In this case, Kony Mobile Application Server passes the values. Example HTML: <input type = "text" name = "searchType" id = "searchType" value="submit" /> The corresponding parameters in the DSL file using two arguments is as shown below: optionalpostparam `searchType `submit submit is the static value of the parameter searchType optionalpostparam `searchType `ignore if a value is specified for the searchType parameter, the provided value is considered, else this parameter is skipped Copyright © 2012 Kony, Inc. All rights reserved. Page 588 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool optionalpostparam `searchType `"" indicates that the searchType parameter does not have any value optionalpostparam `searchType `'' indicates that the searchType parameter does not have any value Three Arguments Syntax optionalpostparam ` <parameter1> ` <parameter2>` ignore|""|''|<staticvalue> Parameter parameter 1 parameter2 staticvalue ignore Description alias name of the parameter name of the parameter static value of the field used when you want to pass optionalpostparam values dynamically. In this case, Kony Mobile Application Server passes the values. Example DSL file content to scrape data when using three arguments: # alias name parameter is used when the field you are specifying has an alias name associated with it optionalpostparam optionalpostparam optionalpostparam optionalpostparam `alias `alias `alias `alias name name name name `searchType `searchType `searchType `searchType `submit `ignore `"" `'' repeatpostparam This parameter is used when you want to pass input data to the fields that have same name but different values. For example, if you specify the pick-up and drop locations for a Car Search, use this parameter if both these fields have the same name like "location". Though the name is same, these two fields have different values. Syntax repeatpostparam `paramname Parameter paramname Description name you want to give to the parameter that passes values to the fields that have the same name on the web page (value of attribute of param tag in Service Definition file). This is equivalent to the name of postparam of URL for which you are posting data Copyright © 2012 Kony, Inc. All rights reserved. Page 589 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Example HTML: <select class="carLocation" name="carLocation" id="carOriginLocation"> ...<option selected="selected" value="Airport" > Airport ...</option> ...<option value="City" > City </option> ...<option value="Address" > Address </option> </select> <select class="carLocation" name="carLocation" id="carDestinationLocation"> ...<option selected="selected" value="Same as pick-up">Same as pick-up ...</option> ...<option value="Airport" > Airport ...</option> ...<option value="City" > City ...</option> ...<option value="Address" > Address ...</option> </select> DSL parameters to post carLocation data: repeatpostparam `carLocation optionalheaderparam This parameter is used to pass optional header parameters. Syntax optionalheaderparam `<parameter1> ` ignore|""|''|<staticvalue> for two argument statements optionalheaderparam ` <parameter1> ` <parameter2> ` ignore|""|''|<staticvalue> for three argument statements Parameter parameter1 parameter2 staticvalue ignore Description alias name of the parameter name of the parameter used when you want to pass header values from DSL file used when you want to set it as service call input. This value will be set from the application. Note: This parameter is similar to optionalpostparam except that it passes HTTP header information. Copyright © 2012 Kony, Inc. All rights reserved. Page 590 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Example DSL File content to scrape data: optionalheaderparam `Cookie `ignore optionalheaderparam `User-Agent `value If the Scraper does not get the User-Agent value, the Scraper sets a default value as follows: optionalheaderparam `User-Agent `Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10_5_5; en-us) AppleWebKit/525.27.1 (KHTML, like Gecko) Version/3.2.1 Safari/525.27.1 file This parameter specifies the file from which data is to be scraped. If the content of a web page has been saved to a file, you specify the name of this file. Note: This parameter is used only to test the output in case of multiple service calls. Syntax file `<filename> Parameter filename Description name of HTML/XML content file saved at the same location as that of the DSL file Example DSL file content to scrape data: file `flight_search_page.html a 16.4 Output Parameters This section explains the various output parameters that you may need to use in a DSL file for the Scraper Tool: cookie This parameter is used to extract cookie string from response header. This is an optional parameter. Syntax cookie `<cookiename> Copyright © 2012 Kony, Inc. All rights reserved. Page 591 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Parameter cookiename Description string that is used as a name of output cookie for service call Cookie will be stored as <cookiename>_cookie where <cookiename> is the name of the variable. If this parameter is not provided, then the cookie is stored as <serviceID>_cookie where <serviceID> is the ID of the service for which you are scraping the cookie. Example DSL file content to scrape data: cookie `example Output will be a string stored in example_cookie url This parameter is used to capture the URL of the page that is returned by the Scraper Tool. Example Output of the scraper will be ServiceID_url: (url address) Note: No corresponding parameter is required in the DSL file. field This parameter is used to specify a field either as standalone or a field within a record. Note: You need to scrape all the individual fields first and then start scraping the fields within a record. Syntax field `<fieldname> `<X-Path> or field `<fieldname> `<Regular Expression> `regex|repregex Parameter fieldname X-Path Description name of output parameter for service call Xpath expression to identify data in the result HTML Copyright © 2012 Kony, Inc. All rights reserved. Page 592 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Parameter RegularExpression Description Regular expression to match a string optional parameter used to specify regular expression to identify data optional parameter used to specify regular expression to identify data. This identifies all possible matches. regex repregex field parameter can be used in two ways to extract data from result page: l Using Xpath Syntax field `<fieldname> `<X-Path> Example DSL file content to scrape data: field `contact` //:table//:div[@class ="sectionfirst"]/:p[2]/:strong/text() l Using Regular Expression. It will be useful if you want to extract only specific data in the result HTML. Syntax field `<fieldname> `<Regular Expression> `regex|repregex Example HTML: <input id="id1" name="name1" Value="washington, WAS"/> <input id="id2" name="name1" Value="miami, MIA"/> <input id="id3" name="name1" Value="newyork, NYK"/> <input id="id4" name="name1" Value="chicago, CHG"/> type="radio" type="radio" type="radio" type="radio" DSL file content to extract data: Copyright © 2012 Kony, Inc. All rights reserved. Page 593 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool It is not possible to extract only airport codes using XPath, we will use regular expression to extract it. field `Value ` <input id= "[^"]*" name=" [^"]*" type="radio" Value="[^,] (.+?)" /> `regex Output: WAS field `Value` <input id= "[^"]*" name="[^"] *" type="radio" Value="[^,] (.+?)" /> `repregex Output: WAS, MIA, DCA, DTR record This parameter is used to specify a record of data that contains sub elements defined in the field parameter. Note: The XPath for a field within a record should start with a . (dot). Syntax record `<recordname> `<X-Path> `colparsing Parameter recordname X-Path Description name of output parameter for service call. This name is also used as collection variable in IDE Xpath expression used to identify record data in result HTML optional parameter used to specify evaluation of record data in column-wise or row-wise fashion. This parameters is used: l colparsing l to reduce computation time when the HTML pages are more than 500KB in size and have more data to parse. Note: This parameter does not support the XPath functionality. Copyright © 2012 Kony, Inc. All rights reserved. Page 594 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool Example HTML: <ul class='plain'> ...<div> ......<li>Adak Island ......</li> ......<span class="code"> ......</span> ...</div> ...<div> ......<li>Aberdeen ......</li> ......<span class="code"> ......</span> ...</div> ...<div> ......<li>Abilene ......</li> ......<span class="code"> ......</span> ...</div> ...<div> ......<li>Akiachak ......</li> ......<span class="code"> ......</span> ...</div> </ul> ADK ABR ABI KKI DSL file content to scrape data: record `UScodesA` //:ul[@class='plain']/:div field `UScityA` ./:li field `UScodeA` ./:span[@class='code'] Output: { {UscityA: Adak Island, UscodeA: ADK}, Copyright © 2012 Kony, Inc. All rights reserved. Page 595 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool {UscityA: Aberdeen, UscodeA: ABR}, {UscityA: Abilene, UscodeA: ABI}, {UscityA: Akiachak, UscodeA: KKI } } innerrecord This parameter is used for recursive data within a data record and is similar to record parameter. Note: The XPath for a field within a record should start with a . (dot). Syntax innerrecord `<innerrecordname> `<X-Path> Parameter innerrecordname X-Path Description name of innerrecord output parameter for the service call and is also saved as record in IDE Xpath expression used to identify record data in result HTML Note: At the end of innerrecord, you have to add innerrecord that the innerrecord has ended. `{{reset}} to indicate Example HTML: <div class="airResults"> <div class="results"> <span class="totalPrice">350</span> <div class="resultSlice"> <h4>Departure Flight:</h4> <h4>American Airlines 734 </h4> <dl> <dt>Depart:</dt> <dd>2:30pm</dd> <dt>Arrive:</dt> <dd>9:33am</dd> </dl> </div> <div class="resultSlice"> <h4>Return flight</h4> <h4>American Airlines 503 </h4> Copyright © 2012 Kony, Inc. All rights reserved. Page 596 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 <dl> <dt>Depart:</dt> <dd>4:30am</dd> <dt>Arrive:</dt> <dd>8:40am</dd> </dl> </div> </div> <div class="results"> <span class="totalPrice">340</span> <div class="result"> <h4>Departure Flight:</h4> <h4>American Airlines 734 </h4> <dl> <dt>Depart:</dt> <dd>6:20am</dd> <dt>Arrive:</dt> <dd>7:43am</dd> </dl> </div> <div class="resultSlice"> <h4>Return flight</h4> <h4>American Airlines 1745</h4> <dl> <dt>Depart:</dt> <dd>5:45am</dd> <dt>Arrive:</dt> <dd>5:35am</dd> </dl> </div> </div> DSL file content to scrape data: record `airResults` //:div[@class="airResults"]//:div [@class="result"] field `price` ./:span innerrecord `flightDetails` .//:div[@class="resultSlice"] field `flightName`. /:h4 field `DepartTime` /:dl//:dd[1] Copyright © 2012 Kony, Inc. All rights reserved. Page 597 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 field `ArrivalTime` /:dl//:dd[2] innerrecord `{{reset}} Output: { { price: 350, FlightDetails:{ {flightName: American Airlines 734 , DepartTime:2:30pm, ArrivalTime: 9:33am}, {flightName:American Airlines 503 , DepartTime:4:30am , ArrivalTime: 8:40am } } }, { price: 340, flightDetails: { {flightName:American Airlines 734, DepartTime:6:20am , ArrivalTime: 7:43am}, {flightName: American Airlines 1745, DepartTime: 4:35am , ArrivalTime: 5:35am } } } } hiddenkeyvalue This parameter is used when you want to scrape hidden input values. You have to create a record with its name as hiddenkeyvalue that has fields hiddenkey and hiddenvalue. The names of the record and fields cannot be changed. Example HTML: <form id="form1" action="/airportcodes.html" > <input id="id1" name="name1" type="hidden" Value="washington, WAS"/> <input id="id2" name="name2" type="hidden" Value="miami, MIA"/> Copyright © 2012 Kony, Inc. All rights reserved. Page 598 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 <input id="id3" name="name3" type="hidden" Value="newyork, NYK"/> <input id="id4" name="name4" type="hidden" Value="chicago, CHG"/> </form> DSL File content: record `hiddenkeyvalue` //:form[@id="form1"]//:input [@type="hidden"] field `hiddenkey` ./@name field `hiddenvalue`./@value Output: serviceID_hiddenjson: { "name1":"washington,WAS", "name2":"miami,MIA", "name3":"newyork,NYK", "name4":"chicago, CHG" } error fields This parameter is used to capture the error messages. Scraper Tool returns error messages in errmsg string. If there is more than one error message, Scraper Tool returns a string that contains all the error messages separated by lines. You should use the field parameter to capture individual error messages. Note: The field name that is used to capture the error messages should start with error. For example, errorTop. Example HTML: <div class="main"> ...<div id="errorTop"> ......<p class="error"> We need more information to continue. ......</p> ...</div> ...<div id="airLocation"> Copyright © 2012 Kony, Inc. All rights reserved. Page 599 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 ......<p class="error"> Please enter the name of a city or an airport code and try again. ......</p> ...</div> </div> DSL Syntax to retrieve error messages: field`errorTop` //:div[@id="errorTop"]/:p/text() field `errortext` //:div[@id="airLocation"]/:p/text() Output: "errmsg": We need more information to continue.<br>Please enter the name of a city or an airport code and try again. 16.5 How to Use the Scraper Tool In this section, we have a detailed example that explains every step involved in creating an application that uses the Scraper Tool. Let us develop an application that scrapes the http://www.finance.yahoo.com web page and gets the following stock details of the company we have entered: l Last Trade Value l Trade Time l Prev Close Value. The following are the steps involved in developing an application that uses the Scraper Tool. 1. Create a DSL File and Properties File manually or create an automated DSL file. 2. Deploy Scraper Files 3. Create an application 4. Create the required forms and place the necessary widgets 5. Create a DSL file with the required input and output parameters and also a properties file 6. Create a Java Service that uses this DSL file 7. Generate the Service Definition file 8. Test the Service Response 9. Publish the Service Definition file 10. Create an action sequence on the widget(s) or the form(s) (whichever is applicable) and mapping the data appropriately 11. Build the application 12. Test the output on the emulator. Copyright © 2012 Kony, Inc. All rights reserved. Page 600 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 16.5.1 Step 1: Create a DSL file and the properties file 1. Create a text file and name it as getStockQuoteDetails.DSL . 2. Save the file in <scraper home>/<appID>. In this case, <middleware home>/genericscrapper/GetStockQuotes. 3. Go to the web page http://www.finance.yahoo.com and examine it using Firebug. Click bottom-left corner of the web page to activate Firebug. at the 4. Enter any company name in the text box provided on the web page and click GET QUOTES. 5. Select Last Trade value, right-click and select Inspect Element to get the X-Path you need to specify to extract that data from the web page. Copyright © 2012 Kony, Inc. All rights reserved. Page 601 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 6. Similarly, perform the same action for Trade Time and Prev Close values. 7. Edit the DSL file to look similar to the following: propkeyname `domain repurlparam `company url `http://domain/q?s=company `get ----field `lastTrade `//:table[@id="table1"] //:tr[position()=1]//:span field `tradeTime `//:table[@id="table1"] //:tr[position()=2]//:span field `prevClose `//:table[@id="table1"]//:tr[position()=4] //:td 8. Edit the properties file to have the following content: DEBUG = ALL domain = www.finance.yahoo.com 16.5.2 Step 2: Deploy Scraper Files You have to deploy the following files related to the Scraper Tool on the Kony Application Server: Copyright © 2012 Kony, Inc. All rights reserved. Page 602 of 785 Working with Scraper Tool l DSL File(s) l Properties File Kony Studio User Guide - 2.1 This deployment process enables you to use the application with Scraper Tool on the Kony Application Server. 16.5.2.1 DSL File(s) For each service that uses the Scraper Tool, you should create a DSL File and deploy it on the Kony Mobile Application Server. The DSL files should be deployed on the Kony Mobile Application Server at the following location: home/core/install/genericscrapper/<appID>. Replace <appID> with the application ID for which you will be using the Scraper Tool. For the sample application explained in this document, the path will be home/core/install/genericscraper/GetStockQuotes. 16.5.2.2 <appID>.properties File Deploy the <appID>.properties file on Kony Application Server at the following location: home/core/install/genericscrapper/<appID>. Replace <appID> with the application ID for which you will be using the Scraper Tool. For the sample application explained in this document, the path will be home/core/install/genericscrapper/GetStockQuotes. Note: It is a good practice to restart the Tomcat Server on Kony Application Server after deploying the files. 16.5.3 Step 3: Create an application 1. Launch Eclipse. 2. Open Kony Perspective. 3. Go to Applications View. 4. Right-click and select New Application. Enter the application name as GetStockQuotes. 16.5.4 Step 4: Create the required forms and place the necessary widgets 1. Expand the application. 2. Select forms, right-click and select New Form. 3. Enter the form name as frmGetStkQts. 4. Drag and drop an HBox and drop a Label and a Text Box on to it. Copyright © 2012 Kony, Inc. All rights reserved. Page 603 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 5. Drag and drop a button below the HBox. Set the title of the label and button as shown below: 6. Create another form and name it as frmStkDetails. 7. Drag and drop three HBoxes on to the form. Place two labels on each HBox. 16.5.5 Step 5: Create a Java Service that uses the DSL file 1. Go back to Eclipse. 2. Go to Applications View. 3. Select the application GetStockQuotes, right-click it and select Service Definition -> Java Services. 4. In the Load Java Services Libraries pane, click Load and browse to the location where you have saved the ScraperLibrary jar files, and select all the jar files using the Shift key on the keyboard. Copyright © 2012 Kony, Inc. All rights reserved. Page 604 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 For more information about the jar files for Scarper Tool, see ScraperLibrary jar files. 5. In the Java Services pane, click Add and enter the Java Service name as getStockQuoteDetails. Note: Make sure the service is named exactly as the DSL file. 6. In the Java Service Detail pane, enter the following details: l l Class Name as com.kony.scrapper.gc.ScrapperJavaService. This can be any Java Class that implements the JavaService interface. Method Name as getGenericScrapperData. If you define a Java Class of your own, then this method name should be the method that invokes the getGenericScrapperData method. Note: com.kony.scrapper.gc.ScrapperJavaService class and getGenericScrapperData method are available in the scraper.jar file you have loaded in step 4 above. Copyright © 2012 Kony, Inc. All rights reserved. Page 605 of 785 Kony Studio User Guide - 2.1 Working with Scraper Tool 7. In the Edit Service Parameters pane, under Input Parameters, click Add. Note: The input parameter name(s) should be the same as input parameter(s) in the DSL file. 16.5.6 Step 6: Generate Service Definition File 1. In the Java Service Definition window, click in the toolbar. 2. A confirmation window appears as shown below when the Service Definition file is generated successfully. 16.5.7 Step 7: Test the Service Response 1. In the Java Service Detail pane, click Test. 2. The service is invoked to hit the URL specified in the DSL file (with the test value defined for input parameter) and response is fetched. Copyright © 2012 Kony, Inc. All rights reserved. Page 606 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 3. The output parameters defined in the DSL file populate in the Output Parameters pane. 4. The service response appears in the Result pane. Right-click and select Format to view the response in a readable format. Note: The opstatus parameter populates automatically when the service response is fetched. If the value of opstatus is 0 (zero), it indicates that the service response was successfully fetched. Else, an errmsg parameter is populated automatically that captures the error that occurred while invoking the service. Copyright © 2012 Kony, Inc. All rights reserved. Page 607 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 16.5.8 Step 8: Publish the Service Definition file 1. Go to Applications View. 2. Right-click the application and Publish -> Services. 3. The Publish Services window appears. You can publish the Service Definition file to the same server as mentioned in the Kony Server Properties. If you want to change the location to publish the Service Definition file, you need to uncheck Use URL defined in Properties -> Kony Server. Specify the following details: Copyright © 2012 Kony, Inc. All rights reserved. Page 608 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 i. Protocol - Select the protocol as either http or https. https is for a secured connection. ii. Server Name/IP Address - enter the URL or the IP Address of the server to which you want to publish the Service Definition file iii. Server Port - enter the port number that the server uses. 4. Enter the credentials that are required to access the server. 5. Click Finish. The Service Definition file is published on the specified server. 16.5.9 Step 9: Create an action sequence on the widgets or the forms and mapping the data appropriately To fetch the stock quote of the specified company and display the results on a form, you need to perform the following actions: 1. Invoke the service (hit the URL specified in the DSL file) with the defined input parameter(s). 2. Map the data retrieved from the service call to the widgets on the form so that the data is displayed on the form appropriately. 16.5.9.1 Invoking the Service 1. Open the form frmGetStkQts. 2. Select the Get Stock Details button. 3. Scroll down to the onclick event in the Properties window and click on . Event Editor window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 609 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 4. Right-click Action Sequence and select Invoke Service (Synchronous) or Invoke Service (Asynchronous) based on your requirement. 5. Select getStockQuote Details service from the drop-down list. 6. Click Open Mapping Editor. The Mapping Editor window appears. 7. Filter the source by Widget Category or Widget Id. 8. Map the text in the text box to the service input parameter as shown below: 9. Click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 610 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 16.5.9.2 Mapping the service output to the widgets on the Form 1. In the same Event Editor window, right-click Action Sequence and select Add Decision. 2. Click Decision. i. Click getStockQuoteDetails under Services. ii. Select opstatus:string in the right pane. iii. Equate the expression formed to 0 as shown below: 3. Expand Decision. 4. Right-click true and select Navigate to Form/Popup. 5. Select frmStkDetails from Select Form/Popup drop-down. 6. Click Open Mapping Editor. The Mapping Editor window appears. 7. Filter the source by service Widget Category or Widget Id. Copyright © 2012 Kony, Inc. All rights reserved. Page 611 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 8. Filter target by Widget Category or Widget Id. 9. Map the output parameters in the service to the corresponding labels as shown below: 10. Right-click false and select Show Alert. 11. Click Alert and perform the following actions: i. Select Type as error. ii. Select Message Type as expression. iii. Click getStockQuoteDetails under Services. iv. Select opstatus:string in the right pane. i. Click getStockQuoteDetails under Services. ii. Select opstatus:string in the right pane. iii. In the Message text box, select opstatus from the expression formed and replace it with Copyright © 2012 Kony, Inc. All rights reserved. Page 612 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 the string "errmsg". 12. Click OK. 16.5.10 Step 10: Build the application 1. Go to Applications View. 2. Right-click the application and select Build -> Build or Build -> Clean and Rebuild All. 3. Select the platforms on which you want to build the application in the Build Generation window. For more information, see Building the Application. 4. A green tick mark appears against emulators of all the platforms on which you have built the application. 16.5.11 Step 11: Test the Output on the Emulators 1. Go to Emulators View. 2. Double-click the emulator on which you want to see the application. The application looks as shown below on Basic Mobile Web: Copyright © 2012 Kony, Inc. All rights reserved. Page 613 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 The application looks as follows on BlackBerry Storm emulator (Native App): The application looks as follows on Android (Mobile Web): 16.6 Create a Scraper Service You can additionally create a Scraper Service using the an interface provided in Kony Studio. To edit the properties of a scraper service: Copyright © 2012 Kony, Inc. All rights reserved. Page 614 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 1. On Eclipse IDE, navigate to Applications pane > Services > Scraper . 2. Right-click scraper and click Properties. The Scraper Properties view appears. 3. Under the Kony Parameters tab, perform the following actions: a. Select Connection Library from the dropdown list. b. Select Log Mode from the dropdown menu. Selecting this option enables the logs in the middleware log. The path of the log file is as follows, middleswarehome>genericscraper>appname>logs. Selecting a specific log type enables the logs of that particular type to be saved. c. Select User-Agent from the dropdown menu. Specifying the value as true states that your browsers user agent will be used. Specifying the content as false states that the platforms user agent will be used. d. Enter HttpNoContent: Is an integer value. For http content with a response code 204, the number in this field specifies the number of times the content will be fetched. e. Enter HttpNoContentTimer.Specify an integer value.For http content with a response code 202, this field specifies the number of times the service hits the browser to fetch the content. f. Under the Http Proxy, enter the proxy server details: I. Enter Host. II. Enter UserName. III. Enter Port. IV. Enter Password. 4. Under Other Parameters tab, enter Key and its Value. The keys and values specified are used as global parameters in the DSL file. Use the following procedure to specify the DSL input parameters: Copyright © 2012 Kony, Inc. All rights reserved. Page 615 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 1. Navigate to Applications pane > services > scraper > dsl Copyright © 2012 Kony, Inc. All rights reserved. Page 616 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 2. Right-click dsl, and then click New DSL file. 3. Enter the File Name, and then click Finish. An editor window appears. 4. Enter the parameters as per the dsl format with reference to XPath. A dsl file is created in the following location: <workspace>\<application name>\<services>\<scraper>\<dsl>. The input parameters of the DSL file is listed at Input Parameters. 5. On the Scraper View pane, do the following tasks: a. Under Input Params tab: Copyright © 2012 Kony, Inc. All rights reserved. Page 617 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 a. Under Input Params tab: I. Enter the value for Key. II. Enter a Value. Value is the value that is used for testing the service. This is the value that is substituted during the service call while testing the service. III. Select a value for Scope from the drop-down list. Scope denotes whether the value for the header is taken from the http request or a http session. IV. Click Test. The Output Parameters are populated. b. Under Output Params tab, you can add an output parameter, or edit an existing output parameter. I. Click Add. The Select Categories view appears. Each of the categories represents a category fetched from the service. Copyright © 2012 Kony, Inc. All rights reserved. Page 618 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 II. Select Param/Dataset/Record and then click Next. A new window appears. For Dataset and records create a record and click OK. III. The Output Parameter is created. The purpose of adding, editing, or deleting output parameters is to test the results of the service locally before you publish the service on a server. c. Under the Result tab, you can view the result. d. Under DSL Detail tab: I. Preprocessor Name - Enter the Preprocessor file name. II. Postprocessor Name - Enter the Post Processor file name. Note: For more information on Preprocessor and Post Processor, see the section Preprocessor/Post Processor. Copyright © 2012 Kony, Inc. All rights reserved. Page 619 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 III. Timeout (in ms) - Specifies the maximum time (in milli seconds) the service waits for a response, before terminating the connection to the external data source. IV. Cachable - Specifies if the service response must be stored in the cache. V. Cachable Duration - This option is enabled if you select the Cachable property. This property specifies the time duration in seconds. Note: If this service is Cachable and a call is made before the specified time duration, the service response is fetched from the Cache, else a fresh service call is made to fetch response from the server. I. Browse and Load Pre/PostProcessor Class. 6. Click Publish. 16.7 Testing Scraper Service 1. Once you create the DSL files, navigate to Scraper Input View or go to Window->Show View->Other>Kony Studio -> Scraper Input. 2. Define the input and parameters. Copyright © 2012 Kony, Inc. All rights reserved. Page 620 of 785 Working with Scraper Tool Kony Studio User Guide - 2.1 3. Define the output parameters. 4. Click on Test button. The scraper service is invoked from the IDE. Copyright © 2012 Kony, Inc. All rights reserved. Page 621 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 17. Internationalizing (i18n) Application Content The process of designing or developing an application in such a way that it supports various languages and regions is known as Internationalization. For an application to support Internationalization, you do not need to make any changes in the application code or logic. Internationalization is abbreviated as i18n. i18n support for an application has to be defined at the time of developing the application. 17.1 Resource Bundle Resource bundle is a properties file that contains all the i18n Keys along with their values. The resource bundle is locale specific, that is, you will have one resource bundle per locale. The resource bundle follows the naming convention of <language_Country>.properties . For example, l for English locale in United States, the resource bundle will be en_US.properties l for French locale in Canada, the resource bundle will be fr_CA.properties . 17.2 Implementing Internationalization The current practice to support i18n for applications is to place text (i18n keys) in resource bundles that are loaded into the application. Applications are built to access the resource bundles depending on the selected locale data. For an application to support multiple languages you have to design the application to select the relevant resource bundle at runtime. The keys in the resource bundles are translated to the required languages at runtime. An internationalized application has the following benefits: l the same application can run on multiple locales. l widget's text is not hard-coded in the application. Instead the localized keys are retrieved dynamically. l Support for new locales does not require recompilation. l Region-dependent data such as dates and currencies, appear in formats that conform to the end user's region and language. 17.3 Configuring i18n Locales The IDE provides you with a list of i18n Locales. You have to configure the locales that the application supports. To configure the locales, follow these steps: 1. Go to Applications View. 2. Select an application and expand it. Copyright © 2012 Kony, Inc. All rights reserved. Page 622 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 3. Right-click the application and select Internationalization. Configure Internationalization window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 623 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 4. Click Configure Locales. Configure Locales window appears as shown below: 5. To select predefined locales, click the Predefined Tab. 6. Select the locales that the application supports by selecting the checkbox besides the Language column. Copyright © 2012 Kony, Inc. All rights reserved. Page 624 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 7. To set a custom locale for an application, select the checkbox next to the Language column. 8. Click OK. The locales are configured and appear as columns in the Configure Localization window. Note: For every locale you configure, a corresponding empty folder is created in <workspace>\<application>\resources\common as shown below: As and when you configure internationalization data for a specific locale, the corresponding folder is populated with data. Else, the folder remains empty. Copyright © 2012 Kony, Inc. All rights reserved. Page 625 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 Important: Empty folders for locales are not supported on iPhone. If a locale specific folder is empty, the application crashes on iPhone. Defining i18n Keys When you have defined the required locales for the application, you can also define the keys for internationalization. To define keys, follow these steps: 1. Add a key in the Key column. 2. Specify the internationalized under the respective column for each of the locales. Alternatively, you can also load a resource bundle (with the keys and corresponding values) for each of the locales. For example, to define i18n keys for Month and Weekday for Calendar, define an array of values that are comma separated. (12 values for moth and 7 values for a week). l l The keys to be specified for days of the week should be of the form platform.calendar.day i.e platform.calendar.monday The keys to be specified for months should be of the form platform.calendar.month i.e platform.calendar.january The keys to be specified for days of a month should be of the form platform.calendar.date i.e platform.calendar.1 The snapshot below is an excerpt for how calendar i18n keys are configured and the corresponding output in the emulator. Copyright © 2012 Kony, Inc. All rights reserved. Page 626 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 When a user has zoomed in or zoomed out a map to its maximum possible level and still tries to zoom in or out, you can define an i18n key for the error message to be displayed to the user. The keys to be specified are as follows: l l l l l l platform.map.maxzoomin -- text to display in alert when the map is already in the maximum zoomed in level. platform.map.maxzoomout -- text to display in alert when the map is already in the maximum zoomed out level platform.map.seedetails -- to internationalize the text of "see details" button in the dialog that is displayed when the onselection is defined for map widget. platform.map.cancel -- to internationalize the text of "cancel" button in the dialog that is displayed when the onselection is defined for map widget. platform.map.ok -- to internationalize the text of "ok" button in the dialog that is displayed when the onselection is not defined for map widget. platform.map.description -- The first line of description that signifies how to navigate on the map. 17.4 Configuring Default Locale for the Application You should configure a default locale for the application. The locale you set as default is used throughout the application unless you specifically change the locale. When the resource bundle for a specific locale is not available, then the application rolls back to the default locale. To configure default locale, follow these steps: 1. Go to Applications View. 2. Select an application and expand it. 3. Right-click the application and select Internationalization. Configure Internationalization window appears. 4. Click Configure Locales. Configure Locales window appears. 5. Select predefined locales to be applied to a key. 6. Select a locale from the drop-down list as the Default Locale. 7. Click Finish. Note: If you do not set a default locale, the locale that appears first in Configure Internationalization window is set as the default locale. 17.5 Configuring Custom i18n Locales The IDE provides you with a list of i18n Locales. You have to configure the locales that the application supports. To configure custom locales, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 627 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Select an application and expand it. 3. Right-click the application and select Internationalization. Configure Internationalization window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 628 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 4. Click Configure Locales. Configure Locales window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 629 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 5. To define custom locales, click the Custom Tab. 6. Click to add a custom locale. The Add custom Locale dialog appears. Note: 1. The Locale field must be of the format aa_AA or aa. For example, jp_JP, or jp would be a valid locale name. 2.The Country field can only contain alphabets . 3. The Language field must necessarily have its first character as an alphabet. Copyright © 2012 Kony, Inc. All rights reserved. Page 630 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 7. Click OK. The Configure Locale dialog appears 8. To set a custom locale for an application, select the checkbox next to the Language column. Copyright © 2012 Kony, Inc. All rights reserved. Page 631 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 9. Click OK. The locales are configured and appear as columns in the Configure Localization window. Note: For every locale you configure, a corresponding empty folder is created in <workspace>\<application>\resources\common as shown below: As and when you configure internationalization data for a specific locale, the corresponding folder is populated with data. Else, the folder remains empty. Important: Empty folders for locales are not supported on iPhone. If a locale specific folder is empty, the application crashes on iPhone. Copyright © 2012 Kony, Inc. All rights reserved. Page 632 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 Defining i18n Keys When you have defined the required locales for the application, you can also define the keys for internationalization. To define keys, follow these steps: 1. Add a key in the Key column. 2. Specify the internationalized value under the respective column for each of the locales. Alternatively, you can also load a resource bundle (with the keys and corresponding values) for each of the locales. For example, to define i18n keys for Month and Weekday for Calendar, define an array of values that are comma separated. (12 values for month and 7 values for a week). l l l The keys to be specified for days of the week should be of the form platform.calendar.day i.e platform.calendar.monday The keys to be specified for months should be of the form platform.calendar.month i.e platform.calendar.january The keys to be specified for days of a month should be of the form platform.calendar.date i.e platform.calendar.1 The snapshot below is an excerpt for how calendar i18n keys are configured and the corresponding output in the emulator. When a user has zoomed in or zoomed out a map to its maximum possible level and still tries to zoom in or out, you can define an i18n key for the error message to be displayed to the user. The keys to be specified are as follows: Copyright © 2012 Kony, Inc. All rights reserved. Page 633 of 785 Internationalizing (i18n) Application Content l l l l l l Kony Studio User Guide - 2.1 platform.map.maxzoomin -- text to display in alert when the map is already in the maximum zoomed in level. platform.map.maxzoomout -- text to display in alert when the map is already in the maximum zoomed out level platform.map.seedetails -- to internationalize the text of "see details" button in the dialog that is displayed when the onselection is defined for map widget. platform.map.cancel -- to internationalize the text of "cancel" button in the dialog that is displayed when the onselection is defined for map widget. platform.map.ok -- to internationalize the text of "ok" button in the dialog that is displayed when the onselection is not defined for map widget. platform.map.description -- The first line of description that signifies how to navigate on the map. 17.6 Adding i18n Content to the Application Before you use the i18n data, you should add the content into the application. You can add i18n content into the application in two ways: l l From the IDE l you can add i18n keys one after the other manually l you can add all the i18n keys at one go from the resource bundle. Programmatically from the code using APIs. Note: You can add i18n keys only after you configure the locales. For more information, see Configuring i18n Locales. To add i18n Keys one after the other from the IDE, follow these steps: 1. Go to Applications View. 2. Select an application and expand it. 3. Right-click the application and select Internationalization. Configure Internationalization window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 634 of 785 Internationalizing (i18n) Application Content 4. Click the row that has Kony Studio User Guide - 2.1 to add the i18n Key. 5. Click under the column corresponding to each locale to add locale values for the i18n Key. 6. Repeat steps 4 and 5 till you add all the i18n Keys and their values. 7. Click Finish. The i18n Keys and their values are added into the application. To load the i18n Keys from a resource bundle, follow these steps: 1. Go to Applications View. 2. Select an application and expand it. 3. Right-click the application and select Internationalization. Configure Internationalization window appears as shown below: Copyright © 2012 Kony, Inc. All rights reserved. Page 635 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 4. Click Load..... Browse for folder window appears as shown below: 5. Browse to the location where the resource bundle exists. 6. Click OK. The resource bundle(s) gets loaded into the application. Note: The IDE loads the keys in the resource bundle to the corresponding locale based on the name of the resource bundle. Copyright © 2012 Kony, Inc. All rights reserved. Page 636 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 17.7 Configuring i18n Key Property for Widgets After you have added the i18n Keys into the application, you need to configure the i18n Key for all the widgets in the application. To configure i18n Key for a widget, follow these steps: 1. Go to Applications View. 2. Select an application and expand it. 3. Select forms and expand it. 4. Double-click the required form to open it. 5. Go to Outline View. 6. Select the widget for which you want to configure the i18n Key. 7. Go to Properties View. 8. Scroll to the property Text i18n Key and click under Value. Select/Search i18n Key window appears as shown below: 9. Select the appropriate i18n Key. Alternatively, you can also enter the first few characters of the i18n Key under Search and all the keys that begin with those characters are listed. Select an i18n Key. 10. Click OK. The widget is configured with the i18n Key. Copyright © 2012 Kony, Inc. All rights reserved. Page 637 of 785 Internationalizing (i18n) Application Content Kony Studio User Guide - 2.1 For more information about i18n Key property of each widget, see Kony Widget User Guide. 17.8 Internationalizing Splash Screen and Application Name Kony Studio provides you the option of internationalizing the splash screen and the application name used within an application. As a prerequisite, the application must support internationalization. And also, you must configure all the required locales under internationalization. 17.8.1 Splash Screen To internationalize splash screen, follow these steps: 1. Create images suitable for different locales for the splash screen. 2. Place these images under the corresponding locale folders. for example, resources/<platform>/<locale>. Note: Use the same name for the images under different locales. For example, splscreen.png. Important: For Android platform, you must place the images under the folders drawable- <language> or drawable-<language>--r<country>. For example, drawable-en or drawable-fr-rFR. 3. Go to Application Properties and set the same image for splash screen logo. 4. When the application is launched, the images under the corresponding locale are picked and rendered as splash screen for the application on respective locales. Copyright © 2012 Kony, Inc. All rights reserved. Page 638 of 785 Kony Studio User Guide - 2.1 Internationalizing (i18n) Application Content Important: For Windows Phone 7, if you have both common and locale specific splash screen images, the common image is shown first and then the locale specific splash screen is displayed. This is a platform limitation. To overcome this, do not include a common image to display the locale specific splash screen with a delay. iPhone To internationalize the splash screen on iPhone, follow these steps: 1. Create an image with the name Default.png and its retina image [email protected] in en.lproj folder. 2. Add the files to the project from Xcode: i. Right-click VM project in the left pane of Xcode. ii. Select Add->Existing Files… iii. Add Default.png and [email protected] . 3. Similarly, place the locale specific images in the locale specific folders. For example, splash screen image for French language should be placed under fr.lproj folder with the same names Default.png and [email protected]. 4. When you build the application and switch to the respective locale, you can see the corresponding splash screen for that locale. 17.8.2 Application Name The name you specify while creating an application can also be internationalized for different locales. When you change the locale on the mobile device, the application name for the corresponding locale is used. BlackBerry Configure a key platform.appname and provide the application name under each locale while configuring the internationalization keys. For example, bb.appname . Note: If the locale the mobile device is referring to is not configured in the IDE, the application falls back to the default locale. iPhone 1. Navigate to the luavmiphone folder. 2. Create a file named InfoPlist.strings . 3. Add the key CFBundleDisplayName =<locale specific application name>. 4. Add these files to the VM project. (right-click Xcode and select Add -> Existing Files) Copyright © 2012 Kony, Inc. All rights reserved. Page 639 of 785 Kony Studio User Guide - 2.1 Internationalizing (i18n) Application Content 5. Save this file in <language specific>.lproj folder. For example, en.lproj folder for English language, fr.lproj folder for French language. 6. Based on the locale of the mobile device, the corresponding application name is used. Android 1. Create a file named strings.xml with the following content: <?xml version="1.0" encoding="utf-8"?> <resources> ...<string name="app_name">$APPID</string> -- replace $APPID with locale specific application name </resources> 2. Create the locale specific values folders in <workspace>/<project>/resources/mobilerichclient/android. For example, values-en , values-fr , values-en-rUS , values-fr-rFR and so on. 3. Copy strings.xml file to the corresponding locale's values folder. 4. The strings.xml file contains the application generic application name and when you switch the locale, the corresponding strings.xml file is picked up from the appropriate values folder. 17.9 Internationalizing UI Elements and Widget Properties The following is a list for i18n keys that you need to use for different platforms to internationalize UI elements and various properties of widgets. You need to configure these keys in the IDE using the Configure Locales window. 17.9.1 BlackBerry Key Description For application name Text of the Done button as platform.calendar.done shown in the native calendar popup Text of the Select button as platform.calendar.selectdate shown in the native calendar popup Text to be displayed platform.zoomin explaining how to zoomin. Text to be displayed platform.zoomout explaining how to zoomout. Text to be displayed in alert platform.map.maxzoomin when the map is already in the maximum zoomed in level. Remarks platform.appname Applicable only for the native calendar option Applicable only for the native calendar option Copyright © 2012 Kony, Inc. All rights reserved. Page 640 of 785 Kony Studio User Guide - 2.1 Internationalizing (i18n) Application Content Key Description platform.map.maxzoomout platform.map.seedetails platform.map.cancel platform.map.ok platform.map.description Remarks Text to be displayed in alert when the map is already in the maximum zoomed out level To internationalize the text of "see details" button in the dialog that is displayed when the onselection event is defined for map widget. To internationalize the text of "cancel" button in the dialog that is displayed when the onselection event is defined for map widget. To internationalize the text of "ok" button in the dialog that is displayed when the onselection event is not defined for map widget. The first line of description that signifies how to navigate on the map 17.9.2 iPhone Key platform.cancelnetworkbar.cancelkey platform.cancelnetworkbar.loadingmsgkey platform.networkcall.usercancelled exceptionmsgkey platform.networkcall.usercancelled exceptionkey platform.phonewidget.alert.title platform.phonewidget.alert.msg platform.phonewidget.alert.cancel platform.phonewidget.alert.ok platform.nextprevtoolbar.previous platform.nextprevtoolbar.next platform.nextprevtoolbar.done platform.rtwidget.errormsgkey platform.segui.deletebuttontext platform.gridcalendar.error.invaliddate.title platform.gridcalendar.error.invaliddate.msg Description Text on the cancel button The Loading message Message shown when the user cancels the synchronous network call Message Heading shown when the user cancels the synchronous network call Title of the Phone widget Message shown in the Phone Widget Title shown on the Cancel Button Title shown on the OK Button Title shown on the Previous button Title shown on the Next button Title shown on the Done button Message shown when the RTWidget is not able parse the given text Title shown on the Delete button Title of the error message for a grid calendar when you select an invalid date Message shown in the error message for a grid calendar when you select an invalid date Copyright © 2012 Kony, Inc. All rights reserved. Page 641 of 785 Kony Studio User Guide - 2.1 Internationalizing (i18n) Application Content Key Description platform.gridcalendar.error.invaliddate.ok platform.gridcalendar.daynames Title shown on the OK Button in the error message for a grid calendar when you select an invalid date Day names in the grid calendar The following keys are applicable for iPhone, Android, BlackBerry, Windows, and Mobile Web: l platform.calendar.day: The keys to be specified for days of the week. l platform.calendar.date: The keys to be specified for days of a month. l platform.calendar.month: The keys to be specified for months. The following keys are applicable for Mobile Web Key Description To internationalize month names To weekdayI18Nkey Internationalize week names monthI18Nkey Example Value "Jan1,Feb1,Mar1,Apr1,May1,Jun1,Jul1,Aug1,Sep1,Oct1,Nov1,Dec1" "Sun1,Mon1,Tue1,Wed1,Thu1,Fri1,Sat1" The following keys are applicable for Desktop Web and SPA: Key Description To internationaliz monthI18Nkey e month names To weekdayI18Nkey Internationaliz e week names To display an alert message gridCalAlertI18Nkey based on i18n Locale To display an alert message when you gridCalCloseI18Nke close the y calendar based on i18n locales Example Value "Jan1,Feb1,Mar1,Apr1,May1,Jun1,Jul1,Aug1,Sep1,Oct1,Nov1,Dec 1" "Sun1,Mon1,Tue1,Wed1,Thu1,Fri1,Sat1" "User Alert Message" "User Alert Message" Copyright © 2012 Kony, Inc. All rights reserved. Page 642 of 785 Checking APIs and Data Types Kony Studio User Guide - 2.1 18. Checking APIs and Data Types Kony Studio enables you to check the APIs at the time of building the application. Note: The Run API Checker and type checker option is only applicable for Lua application. To enable this feature, navigate to Window > Preferences > Kony Dev Studio > Build and select Run API Checker and type checker. The API checker performs the following actions when a Lua file or a form (that has snippets or functions invoked) is saved in the IDE: 1. Checks for syntactical errors and Lua grammar for error free code format. 2. Facilitates checks on Kony API calls for signature and usage of return type of API calls. An error is displayed if there is a mismatch in the actual signature of the API or the data type of the input and output parameters of an API. 3. Supports partial checking of Lua script files. 4. Displays customized error messages. 5. Facilitates m4 definitions by including those in type checking. 6. Checks for improper data type usage in any binary operation or assignment including duplicate assignment with different data types. 7. Reports errors for multiple return values. 18.1 Limitations API Checker does not support checks for anonymous functions and multiple assignments of variables. Copyright © 2012 Kony, Inc. All rights reserved. Page 643 of 785 Kony Studio User Guide - 2.1 Building the Application 19. Building the Application The build process creates new resources from the existing resources, updates the existing resources, or both. After you develop an application, you must build the application to do the following: l Test the application for its performance and appearance on device emulators. l Publish the application to the specified server. l Install the application on mobile devices. 19.1 Prerequisites l Select the start-up form. Note: The Build process shows an error if you do not set a start-up form. For more information, see creating forms. l Set the various Project Properties. l To build the application on Android platform, the following are the minimum requirements: o SDK Platform Android 1.6, API 4, revision 3 o Google APIs by Google Inc., Android API 4, revision 2 o Latest SDK Platform Tools. 19.2 Build Process When you build an application, all the application components and the user-written code modules are compiled and Lua/JavaScript code is generated for the following: l l l UI Components - forms, popups, images, and widgets Non-UI Components - skins, services, service definition file, project properties, internationalization content User Defined Components - user-written code modules and custom services. The generated Lua/JavaScript code for all the components is collectively known as bytecode. The bytecode denotes various forms of instruction sets that represent the application logic. This bytecode is interpreted by the VM on the mobile devices to run the application. The Lua code is independent of platforms for the UI Components. For Non-UI components and User Defined Components, the Lua/JavaScript code is platform specific. The Lua code files are located at the following location: Platform Common to all platforms Location <workspace>\temp\<project>\output\lua Copyright © 2012 Kony, Inc. All rights reserved. Page 644 of 785 Kony Studio User Guide - 2.1 Building the Application Platform Location <workspace>\temp\<project>\build \server\<platform> For example, Android - l <workspace>\temp\<project>\luasrc\ android Platform specific BlackBerry - l <workspace>\temp\<project>\luasrc\bb iPhone - l <workspace>\temp\<project>\luasrc\iphone Windows - l <workspace>\temp\<project>\build\windows8\Lua The JavaScript code files are located at the following location: Platform Common to all platforms Location <workspace>\temp\<project>\jsoutput\js <workspace>\temp\<project>\build \server\<platform> For example, l Android - <workspace>\<project>\temp\jssrc\ android Platform specific l BlackBerry - <workspace>\<project>\temp\jssrc\bb l iPhone - <workspace>\<project>\temp\jssrc\iphone l Windows8: <workspace>\temp\<project>\build\windows8\JS 19.3 Build Procedure When you build older versions of any application (built on Kony Studio versions 2.6 and earlier), the latest version of Kony Studio changes the names of ifdef platform statements to the new names (with your confirmation). Important: Take a backup of your code base (for applications built on Kony Studio versions prior to 5.0 and earlier) before building the application in Kony Studio 5.0 and confirming this action as the changes are irrevocable. Kony Studio supports the following types of builds: Copyright © 2012 Kony, Inc. All rights reserved. Page 645 of 785 Building the Application l l l l Kony Studio User Guide - 2.1 Build (Incremental) - Uses the previously built state and applies the modifications to the resources that have changed since the last build. Build (Without Clean) - Builds the application for all the build-related resources without deleting the build resources that were existing earlier. Clean and Build o Ignores any problems in the previously built state. o Deletes all the existing resources related to build and builds the application from scratch. Validate - Validates the application for duplicates Form Names, Skin Names, and Widget IDs. Reports errors if any duplicates are found. After validating the application, you must build the application by selecting an appropriate build type. l l Mobile Web Optimized War Archive (For Production) - Run this action when you want to deploy the application for Mobile Web. For more information, see Building the Application for Mobile Web. Validate Render for Mobile Web - Checks if there are any widgets that have been previously rendered off and if Mobile Web has references to any of those widgets. This option is useful when you are upgrading to Kony Studio from earlier versions. Ensure that all the prerequisites for building an application are met before following the procedure mentioned below. Important: When you build older versions of any application (built on Kony Studio versions 2.6 and earlier), the latest version of Kony Studio changes the names of ifdef platform statements to the new names (with your confirmation). To build an application, follow these steps: 1. Go to Applications view. 2. Right-click the application that you want to build and select Build. Copyright © 2012 Kony, Inc. All rights reserved. Page 646 of 785 Building the Application Kony Studio User Guide - 2.1 3. Select a suitable Build option from the Context Menu. 4. Select the platform (s) for which you want to build the application. You cannot build an application simultaneously for HTML5 and Mixed Mode channels for the same platform. For example, if you are building the application for HTML5 iPhone, you cannot build it for Mixed Mode iPhone at the same time. Note: You can expand BlackBerry and select a specific JDE version to build the application. This option reduces the time taken for build and also the memory usage on the local machine. Each checkbox under BlackBerry corresponds to a unique COD file (BlackBerry deployable) for a specific device configuration. The advantage of generating a unique COD file for each device configuration is to: o specify different images for different form factors. o use newer APIs for the latest JDE versions. Important: Each top-level checkbox in the Build screen corresponds to all the devices that run on that version of JDE. The devices listed in the build screen are just indicative of the JDE version do not imply that those are the only mobile devices supported by Kony Studio. 5. Click Finish. The build generation starts as shown below: i. Click Run in Background if you want to hide the build generation progress window. The build process executes in the background. Copyright © 2012 Kony, Inc. All rights reserved. Page 647 of 785 Building the Application Kony Studio User Guide - 2.1 ii. Select Always run in background to execute the build process in background every time. Note: When you build an application for the first time, XML and Lua code will be generated for all the forms and popups. Subsequently, when you build the application, XML and Lua code will be generated only for the modified forms. iii. Click Details to view the details of the Build process. 6. When the build generation is complete, and build is successful, the Build Generation Status window appears as shown below with a success message. The console also displays a success message as shown below. Copyright © 2012 Kony, Inc. All rights reserved. Page 648 of 785 Kony Studio User Guide - 2.1 Building the Application 19.4 Building Application for Tablet Channels The IDE allows you to build the application specifically for tablet channels. When you build an application exclusively for tablet channel, the IDE picks up the forms and popups designed for the tablet channel and generates the binaries. Also, when you build the application exclusively for tablet channels, the IDE generates code only for those. The IDE uses the set of forms/popups created for tablet channel because the screen resolution of tablets is high as compared to the mobile channels. Tablet iPad Android Tablet Screen Resolution 1024x768 1024x600 To build the application for tablet channel, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Build. Select an appropriate option under Build. The Build Generation window appears. 3. Select the tablet on which you want to build the application under Tablet Channel. 4. Click Finish. The IDE generates code for the selected tablet channels and builds the application. 19.5 Building Application for Mobile Web The Generate War (After build) option allows you to reduce the size of the war file and creates the <AppID>-local.war file. This option allows you to directly test the application without publishing the application. When you use this option, a minifier is executed on all the generated JS and CSS files to reduce the size of the war file. To build application for Mobile Web channels, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 649 of 785 Building the Application Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Right-click the application and select Properties. 3. Navigate to the Mobile Web tab. 4. In the General tab, select Enable Server side Mobile Web in Build Screen, to build applications for the Server side Mobile Web platform. 5. Right-click the application and select Build. 6. Select an appropriate Build option. 7. Select the required Mobile Web Channels and build the application. 8. When the application is built successfully a success message appears on the Console and a war file is created. 9. To optimize the war file creation for Mobile Web, select Generate War (After build) from the Build menu. The war file created for Mobile Web contains a web.xml file that defines the web application structure. For more information about web.xml file, see the appendix web.xml File. 10. When you do this action a -local.war file is created at the following location: <Drive>\<Workspace>\temp\<AppID>\build\wap\build\web. 11. You can use this war file to test the application without publishing it. To view the print statements on the server, In the Thinclient middleware tar file you will have two logger jar files (KonyLogger.jar and KonyLoggerdebug.jar), only one of these jars should be copied to server lib. KonyLogger.jar should be used in UAT/Prod where you don't what any debug logs. Delete this jar when you want to view the print statements on the server. KonyLogger-debug.jar should be used in test environment where you what debug logs. To view an Application on Mobile Web BB 10 Install a VMWare player (VMware-player-5.0.1-894247) and then we need to install BB10 simulator . You can run the simulator from "All Programs -> BlackBerry 10 Simulator" location. Just wait for couple of minutes for VMWare player to setup your BB10 simulator configuration. 19.6 Building an Application for Desktop Web Important: The Desktop Web application can only be built for JavaScript projects. Important: For Internet Explorer users, if your application UI is distorted while previewing, it is due to compatibility-related issues that exist in IE version 8 and 9. For more information, refer Microsoft website: http://windows.microsoft.com/en-in/internet-explorer/use-compatibility-view#ie=ie-10 Copyright © 2012 Kony, Inc. All rights reserved. Page 650 of 785 Building the Application Kony Studio User Guide - 2.1 To build application for Desktop Web, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Build. 3. Select an appropriate Build option. 4. Select Desktop Web from the Desktop Channel and build the application. 5. When the application is built successfully a success message appears on the Console and a war file is created. The Optimized War Archive (For Production) option allows you to reduce the size of the war file and creates the <AppID>-local.war file. This option allows you to directly test the application without publishing the application. To optimize the war file creation for Desktop Web, select Generate War Archive from the Build menu. The war file created for Desktop Web contains a web.xml file that defines the web application structure. For more information about web.xml file, see the appendix web.xml File. When you do this action a -local.war file is created at the following location:<workspace\temp\appid\build\wap\build\appid-local.war . You can use this war file to test the application without publishing it. 19.7 Viewing an Application on Desktop Web When you build the application for Desktop Web, you can view the application on the Desktop Web to test the appearance and performance of the application. You do not need device emulators to view an application for Desktop Web To view application on desktop web, follow these steps: 1. Build the application for Desktop web. 2. Navigate to the Desktop. 3. Enter the following URL in the Address Bar of the browser: http://<IP address of the machine where the application is built>:8888/<ProjectName>/kdw. 19.8 Windows 8 Tablet features Microsoft Windows 8 has 3 major flavors. Kony supports both Lua and JS as development languages to create native apps for all the flavors of windows 8. The following Microsoft Windows 8 platforms are supported: Copyright © 2012 Kony, Inc. All rights reserved. Page 651 of 785 Building the Application l Microsoft Windows 8 on Intel chipset (desktop machines, Intel based surface tablets (scheduled to be released this month sometime)). o l If you want to build native apps for these machines using Kony, you can do it either from windows 7 desktop or windows 8 desktop OS. Microsoft Windows 8 on ARM chipset ( MS surface, ultrabooks) o l Kony Studio User Guide - 2.1 If you want to build native apps for these machines using Kony you must have Kony studio on windows 8 desktop OS. Microsoft Windows 8 on x64 ( mac ,parallels with windows 8) (to be released in 5.0.05) o If you want to build native apps for these machines using Kony you can do it either from windows 7 desktop or windows 8 desktop OS. For Windows Phone 8 native apps: We support both Lua and JS. Hybrid, Mixed mode are not supported. For Windows phone 7.5 (a.k.a Mango): We support both Lua and JS. Hybrid, Mixed mode are not supported. Microsoft has also released a new version, Windows phone 7.8, and this version release is only for Mango devices. This version does not have any new features except the start screen change. Microsoft wants to have a consistent look for the start screen across Windows phones. 19.9 Building an Application for Windows 8 Tablets The Windows 8 application is built on a tablet. To build application for Windows 8, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Build. 3. Select an appropriate Build option. 4. Select Windows 8 and ARM from the Tablet and build the application. 5. When the application is built successfully a success message appears on the Console. 6. You can view the built file at the following location: <Drive>\<Workspace>\temp\<AppID>\build\windows8/Windows8ARM. 19.10 Viewing an Application on Windows 8 Tablet When you build the application for Windows 8 on an Eclipse IDE installed on an OS prior to Windows 8, you can do the following: l View the application on a remote desktop with Windows 8 installed on it. l View the simulator on a remote desktop with Windows 8 installed on it l View the application on the Windows 8 tablet Copyright © 2012 Kony, Inc. All rights reserved. Page 652 of 785 Kony Studio User Guide - 2.1 Building the Application To view the application on a remote desktop or an emulator follow these steps: 1. Navigate to Drive>\<Workspace>\temp\<AppID>\build\windows8\Windows8 2. Copy all the files from this folder except the output folder. 3. Create a folder at any location on the remote desktop with Windows 8 installed, and paste the files in that folder. In this procedure, we presume the name of the folder to be Win8Apprunner. 4. Copy the konywindows8 zip file from the workspacename/temp/applicationname/build/windows8 output folder and place it in the Win8Apprunner folder. 5. Open the command prompt with elevated permissions and enter the following: PackageFromZipFile.bat <<nameof the application>>.zip You can also launch the simulator by navigating to C:Program Files(x86)/Common Files/Microsoft Shared/Windows Simulator/ simulator.exe To run the application on the Windows 8 Simulator: 1. Repeat steps 1 to 5. 2. Open simulator. 3. Open application in simulator. To preview the application on the Windows 8 Simulator: Copyright © 2012 Kony, Inc. All rights reserved. Page 653 of 785 Building the Application Kony Studio User Guide - 2.1 1. Repeat steps 1 to 4 2. Copy "JS" and "LUA" folders from workspacename/temp/applicationname/build/windows8 to same folder where Win8Apprunner is created. 3. Open the command prompt navigate to Win8Apprunner folder and enter the following: //For JS preview in local system : Previewpackage.bat JS //For JS preview in Simulator : Previewpackage.bat JS simulator //For Lua preview: Previewpackage.bat Lua //For Lua preview in Simulator: Previewpackage.bat Lua simulator To view the application on the tablet, follow these steps: 1. Navigate to Drive>\<Workspace>\temp\<AppID>\build\windows8\Windows8ARM 2. Copy "Windows8ARM" folder to Surface/Tablet with USB. 3. Ensure developer license is available on Surface/tablet. If developer licence is not available on the system, install developer license using PowerShell. l Open powershell with elevated permissions. l Type Run show-windowsdeveloperlicenseregistration in PowerShell window. l Provide live account details and get a developer license. Copyright © 2012 Kony, Inc. All rights reserved. Page 654 of 785 Building the Application Kony Studio User Guide - 2.1 4. Install Certificate : install the kony.cer or other provided .cer file on tablet/surface. The certificate file can be found at "Windows8ARM" folder. l l l l Double click the .cer file. Certificate dialog box pops up. Chose "Install Certificate…". "Certificate Import wizard" opens up. Chose "Local Machine". Place certificate in "Trusted Root Certification Authorities" first and then Install certificate to Local Machine - Personal using the same wizard. Install the certificate to Current User - Trusted Root Certification Authorities and Current User > Personal again. 5. Run Add-AppDevPackage.ps1 with powershell on device. Open Powershell with elevated permissions, navigate to "Windows8ARM" folder and execute " Add-AppDevPackage.ps1". 6. Observe the successful installation of application. 7. Check your application in start screen. 8. If application is build on Windows 7 system, l Execute "ARMPackageFromZipFile.bat" from Win8AppRunner tool instead of "PackageFromZipFile.bat" on another Windows 8 system. l Verify the appx file is created successfully. l Copy the folder to Device with a USB. l Follow Steps 2 to 7 to install the application. 9. You can also launch the emulator by navigating to C:Program Files(x86)/Common Files/Microsoft Shared/Windows Simulator/ simulator.exe When you build an application on an Eclipse IDE installed on Windows 8 do the following: 1. Go to Applications View. 2. Right-click the application and select Build. 3. Select an appropriate Build option. 4. Select Windows 8 from the Tablet and build the application. App developers can build the application to Intel or ARM architecture. ARM architecture is typically meant for tablets and Intel architecture is meant for desktop/laptop versions. 5. Navigate to the Emulators View. 6. Click on Windows 8 (Local System) to install and view the application on the Local system(desktop). 7. Click on Windows 8 (Simulator) to install and view the application on the on a Windows 8 emulator. Copyright © 2012 Kony, Inc. All rights reserved. Page 655 of 785 Building the Application Kony Studio User Guide - 2.1 19.11 Windows 8 features Microsoft Windows 8 has 3 major flavors. Kony supports both Lua and JS as development languages to create native apps for all the flavors of windows 8. The following Microsoft Windows 8 platforms are supported: l Microsoft Windows 8 on Intel chipset (desktop machines, Intel based surface tablets (scheduled to be released this month sometime)). o l Microsoft Windows 8 on ARM chipset ( MS surface, ultrabooks) o l If you want to build native apps for these machines using Kony, you can do it either from windows 7 desktop or windows 8 desktop OS. If you want to build native apps for these machines using Kony you must have Kony studio on windows 8 desktop OS. Microsoft Windows 8 on x64 ( mac ,parallels with windows 8) (to be released in 5.0.05) o If you want to build native apps for these machines using Kony you can do it either from windows 7 desktop or windows 8 desktop OS. For Windows Phone 8 native apps: We support both Lua and JS. Hybrid, Mixed mode are not supported. For Windows phone 7.5 (a.k.a Mango): We support both Lua and JS. Hybrid, Mixed mode are not supported. Microsoft has also released a new version, Windows phone 7.8, and this version release is only for Mango devices. This version does not have any new features except the start screen change. Microsoft wants to have a consistent look for the start screen across Windows phones. Going forward there will be only two versions of Windows Phone. l Windows phone 8 and above for High end phones (HTC 8x, Lumia 920 etc). l Windows phone 7.8 for Mid-range phones (Lumia 800, Samsung Focus etc). 19.12 Viewing an Application on Windows Phone 8 This section lists the procedure for viewing an application on a Windows 8 Phone. You can test the applications only on a Windows 8 system. To build application for Windows 8, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Build. 3. Select an appropriate Build option. 4. Select Windows 8 from Phone and build the application. 5. When the application is built successfully a success message appears on the Console. Copyright © 2012 Kony, Inc. All rights reserved. Page 656 of 785 Building the Application Kony Studio User Guide - 2.1 6. You can view the built file at the following location: <Drive>\<Workspace>\temp\<AppID>\build\winphone8. Viewing the Application on the Emulator All the emulator setup and requirements are listed at Emulator Setup and Requirements. 1. Right-click the application and build it for Windows Phone 8. 2. The built executable is available at workspace\temp\appname\build\winphone8. 3. Copy the WindowsPhone8.xap file and paste it at any location on a system having a Windows 8 OS. 4. Launch the Application deployment tool. For more information about the Application Deployment tool refer Application Deployment. 5. From the Target drop-down list, select the target emulator on which you want to view your application. 6. Browse for the location where the xap file has been copied to as mentioned in step 3. 7. Click Deploy. 8. If you set the Build mode in IDE as l Debug mode: The IDE automatically launches a Windows Platform Logger when you build the application in the debug mode. An IP Address and Port are listed below in the logger. Copyright © 2012 Kony, Inc. All rights reserved. Page 657 of 785 Building the Application Kony Studio User Guide - 2.1 Enter the IP address and the port listed in the following window that appears. If you want to debug the application then click on "Connect to logger" by providing the corresponding IP address and the port to which the logger is listening to. Click on "Start without logger" , if you want to launch the application without the logger. l Release mode: When you launch the application in the release mode, the application is launched on the emulator directly. 19.13 Building Application for Windows Kiosk To build application for Mobile Web channels, follow these steps: Copyright © 2012 Kony, Inc. All rights reserved. Page 658 of 785 Building the Application Kony Studio User Guide - 2.1 1. Go to Applications View. 2. Right-click the application and select Build. 3. Select an appropriate Build option. 4. Once the application is built successfully for Windows, navigate to the emulator view and launch the application for Windows Kiosk. 19.14 Combining Mobile Web with Middleware Archive for Application servers (WebLogic or WebSphere) The Combine Mobile Web + Middleware Archive option allows you to combine the Mobile Web war file and Middleware war/ear file. This window allows you to build the Mobile Web war file if not already built and then combine it with middleware war/ear file that can be used for application servers ( WebLogic or WebSphere). It allows you to customize the combined web.xml file. To combine Mobile Web war with Middleware Archive, follow these steps: 1. Go to Applications View. 2. Right-click the application and select Combine Mobile Web + Middleware Archive. The Build Archive for project : <project name> window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 659 of 785 Building the Application Kony Studio User Guide - 2.1 3. The Session Manager value is displayed as specified in the Application Properties window. The default value is Kony Session Manager. To change the session manager: a. Right-click the Application and select Properties . The Application Properties window appears. b. Navigate to the Mobile Web tab. c. In the General tab, change the option in the Session Manager dropdown. 4. Click Build optimized war to generate the war file. The generated war file location is updated in the Mobile Web war display field. 5. Click Browse to select the Middleware war/ear that you want to combine with Mobile Web war. 6. The default value of the Context is as specified in the Application Properties > KonyServer tab > Web Context > Middleware window. 7. Select the File Type of the output to be generated ( war or ear). 8. To add your own custom jar files, click Add and select the jar files. You can add multiple jar files. To delete a dependency jar file, select the jar file and then click Delete . 9. Click Next. The Edit web xml window appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 660 of 785 Building the Application Kony Studio User Guide - 2.1 10. This window enables you to add or update xml file with Custom Listeners, Custom Filters, Custom Servlets and Servlet Mappings. The information entered in these tabs is persistent on clicking Finish button. The information is saved even after you close your project. 11. Click Next. The Final web.xml file with all the above mentioned details will be displayed. You can also update the information in this window, but the edited information in this window is nonpersistent. 12. Click Finish to generate the war file. 19.15 Viewing an Application on Emulators When you create an application in Kony Studio and build it, the IDE provides you the option of testing the application for appearance and performance. You need device emulators to do this. These emulators are provided by the device manufacturers or mobile platform vendors. Note: You should have the emulators configured to view or test an application on the emulators. For more information about configuring emulators, see Kony Studio Installation Guide. To view application on an emulator, follow these steps: 1. Build the application. 2. Go to Emulators view. Copyright © 2012 Kony, Inc. All rights reserved. Page 661 of 785 Kony Studio User Guide - 2.1 Building the Application 3. Double-click the emulator on which you want to view the application. 4. The emulator opens. l l On Android emulator, the application opens automatically. On BlackBerry Storm emulator, you must navigate to the Downloads folder and select the application. Important: You can open only one instance of BlackBerry emulator at a time because the BlackBerry emulators bind to a specific port for communication with MDS or Debugger. l Navigate to the application and to view it on the emulator. The emulators are as shown below: Storm Emulator BlackBerry Bold Emulator Android Native App Android Mobile Web Copyright © 2012 Kony, Inc. All rights reserved. Page 662 of 785 Building the Application Kony Studio User Guide - 2.1 19.15.1 iPhone/iPad Emulator Apple has developed a product suite Xcode to develop applications on Mac OS X. The latest version of Xcode is bundled free with Mac OS X, but it is not installed by default. You have to explicitly install it from the Mac OS X DVD or download Xcode from the Apple website at http://developer.apple.com/technologies/tools/Xcode.html. Note: Support for iPhone 3G devices has been dropped. If you install Xcode 4.5, iOS 5.0 SDK is bundled along with it. Xcode is a full-featured IDE. Xcode integrates the editing of source code with the build and compile steps. For more information about Xcode setup for iPhone, see Xcode User Guide. Perform the following steps before running the application on iPhone emulator: 1. Download iOS SDK 5.0 from http://developer.apple.com/iphone/index.action. 2. Install this SDK on the Apple Macintosh machine. 3. Open Xcode. Note: Minimum version of Xcode supported is 4.5 and above for iOS SDK 5.0 version. 4. Select Active Configuration as Release/Debug/Preview in the top-left drop-down in Xcode editor. 5. Select Project/Edit Active Target -> Release/Debug/Preview from Xcode menu. 6. Select Build/Clean All Targets from Xcode menu. To view an application on iPhone/iPad emulator, follow these steps: 1. If you are downloading the plugins manually, download the iphone binaries from the download site provided by Kony and extract them to a folder, say <HOME> . For more information about installing iPhone plug-in, see Kony Studio Installation Guide. When you use the installer, the binaries are downloaded automatically. 2. Go to Terminal and enter the following commands: cd <HOME> cd VMAppWithKonylib\gen perl extract.pl <URL of app KAR> For example, perl extract.pl http://10.10.4.87:8888/TestAppr?type=ipad cd .. open VMAppWithKonylib.Xcodeproj Copyright © 2012 Kony, Inc. All rights reserved. Page 663 of 785 Building the Application Kony Studio User Guide - 2.1 Note: For ease of development and deployment to an iOS simulator , Kony Studio packages the application and its resources into a simple binary format referred to as KBF (KonyBinaryFormat) , also referred to as KAR (KonyArchive). This file includes all the application resources like application byte code , images, and FFI dependencies. The KBF/KAR file is generated every time a build is performed for the iOS platform. This file is deployed to the local Jetty server in the IDE and can be downloaded via HTTP, for example, http://ipaddressof the system:portno/appnamer/?type=iphone Note: If there are Jetty connectivity issues when working with Parallels on Macintosh machine, it is best to use absolute file reference to the KAR file to be extracted, versus via the Jetty Server (KAR file specified as an HTTP url). A given Kony Studio Application's Xcode KAR file is located in your workspace's WebApps directory. If you are using a dual partition Mac/Windows laptop, the absolute file path would look like: perl extract.pl /Volumes/C/Workspace-V4.0.02GA/webapps/GMr/kbf/konyappiphone.KAR 3. Select Scheme as KDebug, KRelease, or Preview. Set the scheme as : l l l KRelease for applications you want to release for Production. KDebug for applications you want to debug. To debug the application, the application must be built in the debug mode in Kony Studio. KPreview for previewing the applications. 4. Click Run in Xcode . This action builds and runs the current application. Note: Close the simulator if it is already open before clicking Run. For iPhone 5, you have to perform an additional step. For more information, refer Viewing applications on the iPhone 5 simulator. Copyright © 2012 Kony, Inc. All rights reserved. Page 664 of 785 Building the Application Kony Studio User Guide - 2.1 5. The simulator opens with Build Succeeded message and the application opens. Note: For information on debugging an application, see the Debugger section. Viewing applications on the iPhone 5 Simulator iPhone 5 is a 4 inch device with 1136 x 640 resolution. This would give extra vertical space for applications, while the width of the screen remain the same as that of old iPhone devices. All existing applications would work on iPhone 5 with out any issues in compatibility mode ( letterbox mode) where the extra vertical space is filled with a black patch on top and bottom of the screen. Applications look good in the compatibility mode and function as they would on any other iPhone devices. 1. For building, running, and testing the application, use the Xcode 4.5 and use the iPhone 5 simulator. Using Xcode 4.5 is compulsory for testing the applications on iPhone 5 in full compatibility mode. Use the prior procedure to launch the simulator. 2. Once the simulator opens up, you can set the simulator as iPhone 5 by choosing the Hardware / Device / iPhone (Retina 4- Inch) 3. Now the application runs in iPhone 5 full mode where the application occupies the complete screen . Copyright © 2012 Kony, Inc. All rights reserved. Page 665 of 785 Building the Application Kony Studio User Guide - 2.1 4. Check the following while testing. o Landscape screens o Rotation experience Note: It is a choice of the customer whether the application will run in full mode or compatibility mode on iPhone 5. Full mode ensures that the application occupies the complete screen that does not necessarily mean the application is really leveraging the extra vertical space . To ensure the applications run on full screen mode refer Splash Screen Properties for iPhone5. Note: The above notes are applicable for the new iPod as well. 19.16 Viewing an Application on Mobile Web When you build the application for Mobile Web, you can view the application on the Mobile Web to test the appearance and performance of the application. You need device emulators to do this. These emulators are provided by the device manufacturers or mobile platform vendors. Note: You should have the emulators configured to view or test an application on the emulators. For more information about configuring emulators, see Kony Studio Installation Guide. To view application on mobile web of a mobile device, follow these steps: 1. Build the application for mobile web. 2. Go to Emulators View. 3. Launch the required emulator by double-clicking the emulator. 4. Navigate to the browser of the emulator. 5. Enter the following URL in the Address Bar of the browser: http://<IP address of the machine where the application is built>:8888/<ProjectName>/p. This port number 8888 corresponds to the number entered in the Embedded Server dialog in the Preferences dialog. If the pre - configured port number is 8888, to launch the application without webcontext : http://localhost:8888/AppiD/p with webcontext: http://localhost:8888/webcontext/p The application built for the mobile web on the corresponding platform launches in the browser of the emulator. Copyright © 2012 Kony, Inc. All rights reserved. Page 666 of 785 Kony Studio User Guide - 2.1 Building the Application Note: If you want to view the application in the web browser of your computer, you can also use the following address apart from the address mentioned earlier: http://localhost:8888/<ProjectName>/p. 19.17 Publishing the Application To make an application accessible from the server, you need to publish the application. The application will be published to the server that is specified in the Kony Server Properties. To publish an application, follow these steps: Important: The procedure given below is applicable only for publishing on Tomcat Server. 1. Go to Applications view. 2. Select the application you want to publish and build it. 3. When the application is built successfully, right-click the application and select Publish -> Application. 4. The Publish Application window appears. 5. Select the platforms on which you want to publish the application and click Finish. Note: The application should have been built on a specific platform to publish it on that platform. For example, if you have not built an application on Android platform, you cannot publish it to Android. Before publishing the application, ensure the following files are available in their respective folders: File KonyWebCommons.jar Applicable to... SPA, Desktop Web, and Thin Client deviceDetectionLogic.xml SPA and Thin Client Stored Location <TOMCAT HOME>/lib <MIDDLEWARE HOME>/middlewarebootconfig/tc Copyright © 2012 Kony, Inc. All rights reserved. Page 667 of 785 Kony Studio User Guide - 2.1 Building the Application File tc-middlewarelib<Version-number>.tar Applicable to... Thin Client Stored Location Extract the tar file into <TOMCAT HOME>/lib Note: You can download all the above files from their respective folders in the Kony Plug-in Releases Web portal. For more information, see Kony Server Installation Guide for Tomcat. 6. When the publishing is in progress, the Publish Operation Status window appears as shown below: 7. When the publish is successful, the console shows a success message. Copyright © 2012 Kony, Inc. All rights reserved. Page 668 of 785 Debugging Applications Kony Studio User Guide - 2.1 20. Debugging Applications Kony Studio provides you with a debugger that you can use to detect and diagnose errors in your applications. The debugger allows you to control the execution of your application by allowing you to: l Set breakpoints l Suspend launched applications l Step through your code l Examine the contents of the variables and view them on an emulator. Note: Debugging is currently not supported on Windows Phone, Palm, and Symbian platforms on Lua. You can debug an application only on one platform at a time. The debugger has a client and server design. This design allows you to debug applications that are running remotely in the network as well as the applications running locally on your workstation. The debugger client runs inside the workspace on your workstation. The debugger server runs on the same computer as the applications you want to debug. The application can be launched on your workstation or on a computer that is accessible over the network. This section contains the following: l Before you Begin l Setup a JavaScript Application for Debugging o Setup iPhone Application o Setup Android Application l Setup a Lua Application for Debugging l Debug Configurations l Kony Debug Perspective l Debugger Operations l Breakpoints l Stepping Through an Application l Evaluating an Expression l Debug an Application l Debugger Behavior while Debugging Mobile Web Applications Copyright © 2012 Kony, Inc. All rights reserved. Page 669 of 785 Debugging Applications Kony Studio User Guide - 2.1 20.1 Before you Begin Before you begin debugging, you must ensure the following: l l The following plug-ins are available either in the dropins or plugins folder of Eclipse: o org.keplerproject.ldt.debug.core.jar o org.keplerproject.ldt.debug.ui.jar o org.keplerproject.ldt.launcher.jar The Build field is set to Debug option. To check if the build field is set to the Debug option, open Project Properties, and select the Build tab. The Build field should be set to Debug. 20.2 Setting Up a JavaScript Application for Debugging To detect and diagnose errors in your application, you must debug an application. To do this you must launch your application in the Kony Debug Perspective. Note: Debugging is currently not supported on BlackBerry, Windows Phone, Palm, and Symbian platforms on JavaScript. You can debug multiple virtual projects and application simultaneously. 20.2.1 Setting up an iPhone Application for Debugging For iPhone applications: 1. Before debugging the application, build the application on Kony Studio and on your mac machine extract the built .kar file. 2. Open the Xcode project. 3. Select the target as KDebug, choose an emulator and click Run. The emulator is launched and the following dialog appears: Copyright © 2012 Kony, Inc. All rights reserved. Page 670 of 785 Debugging Applications Kony Studio User Guide - 2.1 4. Select Start. The waiting for debugger dialog appears. 5. To debug the application on Kony Studio, refer Setting up KonyStudio for Debugging. 20.2.2 Setting up an Android Application for Debugging For Android applications: 1. Before debugging an application, build and launch the application on the emulator. The application must be running in the debug mode on the emulator for you to debug the application. When the application is launched on the emulator, the Debugger Configuration dialog appears. 2. Select Start. The waiting for debugger dialog appears. 3. To debug the application on Kony Studio, refer Setting up KonyStudio for Debugging. 20.2.3 Setting up Kony Studio for JavaScript Application Debugging 1. Navigate to Kony Studio, right-click the application and select Debug As > Debug Configurations. The Debug Configurations view appears. Copyright © 2012 Kony, Inc. All rights reserved. Page 671 of 785 Debugging Applications Kony Studio User Guide - 2.1 2. Right click Kony Application and select New 3. Specify the following configuration details for debugging the iPhone/ Android applications: l Host: Specify the URL of the emulator. l Port: Specify the port number on which the debugger runs. l Show debugger network communication console: If selected, all the communication logs between the host running the emulator and IDE are shown in the Console View. 4. Choose the debug configuration and select Debug. A confirmation dialog appears. 5. Select Yes to debug the application. Select No to continue with your application without debugging. Copyright © 2012 Kony, Inc. All rights reserved. Page 672 of 785 Debugging Applications Kony Studio User Guide - 2.1 6. When you select Yes, the following dialog appears: 7. Select Yes. The Kony Debug Perspective opens. You can now debug the application using the Debugger Operations. Note: On iPhone the form loads after the postappinit event,whereas in Android the control is passed to load resources() function in startup.js after the postappinit event. 20.3 Setting Up a Lua Application for Debugging To detect and diagnose errors in your application, you must debug an application. To do this you must launch your application in the Kony Debug Perspective. To setup an application for debugging, follow these steps: 1. Build the application for the supported platforms as per your requirement in debug mode (see Before you Begin section). Important: Even if you build the application for multiple platforms, you can debug an application only on one platform at a time. 2. From the Navigator View, go to <Application Name> -> luasrc -> Platform Specific Folder. The Platform Specific Folders appear only for the platforms that you have built the application for. Depending upon the platform on which you want to debug, expand the appropriate folder (android, bb, j2me, iphone, tabrcandroid, ipad, or tc). The following image illustrates the platform specific folders generated for Android, Blackberry, and iPhone in the Navigator View: Copyright © 2012 Kony, Inc. All rights reserved. Page 673 of 785 Debugging Applications Kony Studio User Guide - 2.1 3. Under the generated folder, double click the code module of the application that you want to debug. The code module opens in the Script Editor. The following image illustrates the generated folder for Android: Copyright © 2012 Kony, Inc. All rights reserved. Page 674 of 785 Debugging Applications Kony Studio User Guide - 2.1 Note: For accurate debugging, you must use the code modules present in the generated folder to debug the application. These code modules contain the platform specific properties and code statements specific to the platform that the application is built for. 4. Add the Breakpoints. 5. Launch the emulator from the Emulators view. Note: For debugging on Blackberry, use an emulator which is running on JDE 5.0 or above. Important: If you are debugging on iPhone or iPad, do not launch the emulator at this stage. Important: To debug an Application on Mobile Web platform, from the device browser, access the URL of the Application which is hosted locally (you cannot debug a published Application). The debug session begins once the URL opens. 6. Right-click in the Script Editor and from the Context Menu, select Debug As -> Debug Kony Application. The following image illustrates the Context Menu: Copyright © 2012 Kony, Inc. All rights reserved. Page 675 of 785 Debugging Applications Kony Studio User Guide - 2.1 7. A confirmation window appears asking if the project is built with the Debug option. Select Yes. Switch to Kony Debug Perspective dialog appears. Note: If you select No, you are returned to the Script Editor. 8. Select Yes. The Kony Debug Perspective opens and the application can be viewed on the emulator. You can now debug the application using the Debugger Operations. Important: To debug the application on iPhone or iPad, launch the application in debug mode on iPhone emulator at this stage. For information on launching the application in debug mode on iPhone emulator, click here. 20.4 Debug Configurations for Lua The Debugger does not launch any emulator by default. You must manually launch the appropriate emulator to perform the debugging. You can use the Debug Configurations window to create debug configurations for Android, Blackberry, J2ME, and Android tablet and use them to launch the emulator automatically for debugging. To modify the Debug Configurations 1. Right-click in the Script Editor (either in Kony Perspective or Kony Debug Perspective) to open the context menu. The following image illustrates the Context Menu: Copyright © 2012 Kony, Inc. All rights reserved. Page 676 of 785 Debugging Applications Kony Studio User Guide - 2.1 2. Select Debug As -> Debug Configurations.... 3. Double Click Kony Application on the left pane. A Configuration pane appears to the right as illustrated by the image below: 4. The Configuration window has the following fields: Name: Enter a descriptive name for the configuration. Copyright © 2012 Kony, Inc. All rights reserved. Page 677 of 785 Debugging Applications Kony Studio User Guide - 2.1 Project: Displays the currently launched project. You can click the Browse to select another project. Socket Timeout: Specifies the maximum amount of time in seconds before which the application on the emulator must send a response. Else, the connection will timeout and an error is displayed. TCP Port: Displays the port number used for the connection. This field is non-configurable. If you want to change the port number in the Debug Configurations window, open Kony Studio Preferences window, expand Kony Dev Studio -> Debugger, and change the port number. Select emulator to debug: Specifies if the emulator configured in the IDE must be launched to debug. By default, the Launch emulator configured in IDE in Emulator View option is not selected and you can launch either the Android, Android Tablet, Blackberry, J2ME, Mobile Web, iPhone, or iPad emulator manually to debug the application. If you want to launch either the Android, Blackberry, J2ME or Android Tablet emulator automatically, select the Launch emulator configured in IDE in Emulator View option. The Android, Blackberry and Android Tablet emulators are now available for selection. Click the drop-down arrow against the Android emulator and select the desired version of the emulator, or select the radio button against Blackberry or Android Tablet and select the desired version of the emulator. Note: Only the emulators configured in the IDE are displayed in the Debug Configurations window. 5. Click Apply. The configuration is saved with the name you specified in the Name field and is listed under Kony Application. 6. Click Close to close the window. Note: To debug an application using the created debug configuration, launch the Debug Configurations window in the code module and select the created debug configuration and click Debug in the right pane. You can debug an application using the last used debug configuration by pressing f11 on the keyboard. 20.5 Working in the Kony Debug Perspective The Kony Debug Perspective consists of the following views: l Debug View l Navigator View l Applications View l Breakpoints View l Variables View l Script Editor Copyright © 2012 Kony, Inc. All rights reserved. Page 678 of 785 Debugging Applications l Emulators View l Skins View l Properties View l Console View l Outline View l Services View l Progress View Kony Studio User Guide - 2.1 The following image illustrates the Kony Debug perspective and its views: Copyright © 2012 Kony, Inc. All rights reserved. Page 679 of 785 Kony Studio User Guide - 2.1 Debugging Applications 20.5.1 Debug View Debug View allows you to manage the debugging of an application. The application debugging information is shown in a tree hierarchy. This view displays the stack frame for the suspended threads of the application you are debugging. Each thread in your application appears as a node in the tree. It also displays the process for the application you are debugging. If you suspend a thread, its stack frames are shown as child elements and you can use the step controls to step through the execution of the application line-by-line. The following image illustrates the Debug View: You can use the following execution control command buttons (accessed from the toolbar of the Debug View) to change the execution state of code being executed: Command Name Description Resume Resumes the currently suspended thread. Suspend Suspends the selected thread of an application. After the thread is suspended, you can browse, modify code, inspect data, step, and so on. Terminate Terminates the debugging operations. Step Into Steps into the highlighted statement. Step Over Steps over the highlighted statement. Step Return Steps out of the current method. Remove All Terminated Launches Clears the Debug window. 20.5.2 Navigator View Navigator view displays a hierarchical representation of the current workspace and all applications in it. For more information, click here. Copyright © 2012 Kony, Inc. All rights reserved. Page 680 of 785 Kony Studio User Guide - 2.1 Debugging Applications 20.5.3 Applications View Applications view is the starting point for creating an application. For more information, click here. 20.5.4 Breakpoints View You can use the Breakpoints View to view or modify the breakpoints you have added. The following image illustrates the Breakpoints View: You can use the following toolbar items to work with the breakpoints: Command Name Remove All Description Removes all breakpoints. Remove Selected Breakpoints Removes only the selected breakpoints. Show Supported Breakpoints Go to File Skip All Shows only the breakpoints that are applicable to the current application. Opens the location of the breakpoint in the Script Editor. All breakpoints are set to be skipped. 20.5.5 Variables View You can use the Variables View to view the information related to the variables associated with the stack frame (selected in the Debug View). When debugging an application, you can select the variables and see detailed information in the Details Pane. You can also expand the objects to see the fields that the variables contain. The following image illustrates the Variables View with the Detail Pane highlighted: Copyright © 2012 Kony, Inc. All rights reserved. Page 681 of 785 Debugging Applications Kony Studio User Guide - 2.1 20.5.6 Script Editor When you debug an application, the Script Editor is available in the Kony Debug Perspective as a Script Editor in debug mode. You can use the Script Editor (Lua/JavaScript syntax-aware) to view or modify the required application logic. The Script Editor provides the following functionality: l Syntax highlighting l Code Completion l Code wrapping l View listing all the user-written functions l Code Assistance l Syntactical checks Note: You can add or remove breakpoints in the Script Editor. 20.5.7 Emulators View Emulators view displays a list of virtual mobile devices available for testing the application. For more information, click here. 20.5.8 Skins View Skins view displays a list of all widgets along with their associated skins. For more information, click here. 20.5.9 Properties View Properties view allows you to set properties for a widget. For more information, click here. 20.5.10 Console View Console view displays the status of the application during compilation process. For more information, click here. Copyright © 2012 Kony, Inc. All rights reserved. Page 682 of 785 Kony Studio User Guide - 2.1 Debugging Applications 20.5.11 Outline View Outline View displays a list of all the user-defined functions within a Lua/JavaScript file (that is open and is in focus in the Script Editor). For more information, click here. 20.5.12 Services View Services View displays the list of all the services that are associated with the application. For more information, click here. 20.5.13 Progress View Progress View displays the progress of the various operations that can be performed on an application. For more information, click here. 20.6 Debugging Operations You can use the following debugger operations to debug your application: l Breakpoints l Step Controls 20.6.1 Breakpoints When you add a breakpoint, a blue circle ( added. ) appears against the line of code for which the breakpoint is The thread execution suspends before that line of code (where the breakpoint is added) is executed. Note: When a breakpoint is hit or if you are stepping through the code, avoid interactions with the application (click on clickable controls) on the emulator as it can lead to an inconsistent behavior. 20.6.2 Adding a breakpoint You can set a breakpoint on an executable line of an application. The thread execution suspends at that line. To add a breakpoint 1. Open the code modules of the application that you want to debug in the Script Editor. 2. Right-click the vertical ruler to the left of the line where you want to add the breakpoint. A Context Menu appears as follows: Copyright © 2012 Kony, Inc. All rights reserved. Page 683 of 785 Debugging Applications Kony Studio User Guide - 2.1 3. Select Toggle Breakpoint. A breakpoint appears against the line of code as illustrated in the image below: Note: Alternatively, you can double-click on the marker bar next to the source code line to add a breakpoint. 20.6.3 Removing a breakpoint You can remove a breakpoint when it is no longer required. To remove a breakpoint 1. Open the code modules of the application that you want to debug in the Script Editor. 2. Right-click the breakpoint that you want to remove. A Context Menu appears as follows: Copyright © 2012 Kony, Inc. All rights reserved. Page 684 of 785 Kony Studio User Guide - 2.1 Debugging Applications 3. Select Toggle Breakpoint. The breakpoint is removed. Note: Alternatively, you can double-click on the breakpoint to remove it. 20.6.4 Enabling and Disabling Breakpoints When a breakpoint is enabled, the thread execution suspends before that line of code is executed. When a breakpoint is disabled, the thread execution is not suspended by the breakpoint. Note: A breakpoint is enabled by default. You can disable or enable a breakpoint in the Breakpoints view. To disable a breakpoint 1. From the Breakpoints view, deselect the checkbox against the breakpoint you want to disable. The breakpoint image will change to a white circle ( ). This indicates that the breakpoint is disabled. To enable a breakpoint 1. From the Breakpoints view, select the checkbox against the breakpoint you want to enable. The breakpoint image will change to a blue circle ( ). This indicates that the breakpoint is enabled. Copyright © 2012 Kony, Inc. All rights reserved. Page 685 of 785 Kony Studio User Guide - 2.1 Debugging Applications 20.7 Stepping Through an Application You can use the step controls to step through the execution of an application line-by-line when a thread is suspended. While stepping through the application, if you encounter a breakpoint, the execution suspends and the step operation ends. The debugger provides you with the following step controls: l Step Into l Step Over l Step Return 20.7.1 Step Into The Step Into control [ ] in the view toolbar of the Debug View allows you to step into the next method call at the currently executing line of code. To perform a Step Into operation 1. From the Debug View, select a stack frame. The current line of execution in the selected frame is highlighted. 2. Click the Step Into control [ ]. The next expression to be executed is invoked and suspends at the next executable line. 20.7.2 Step Over The Step Over control [ ] in the view toolbar of the Debug View allows you to step over the next method call at the currently executing line of code without entering it. Note: Even though you do not step into the method, the method executes normally. To perform a Step Over operation 1. From the Debug View, select a stack frame. The current line of execution in the selected frame is highlighted. 2. Click the Step Over control [ ]. The selected line executes and suspends on the next executable line. 20.7.3 Step Return The Step Return control [ you have stepped into. ] in the view toolbar of the Debug View allows you to return from a method which Copyright © 2012 Kony, Inc. All rights reserved. Page 686 of 785 Debugging Applications Kony Studio User Guide - 2.1 Note: Even though you return from the method, the code inside the method executes normally. To perform a Step Return operation, follow these steps: 1. From the Debug View, select a stack frame. The current line of execution in the selected frame is highlighted. 2. Click the Step Return control [ ]. The method execution resumes. The method executes until the next return statement in the current method is executed and suspends on the next executable line. 20.8 Evaluating an Expression Kony Studio provides you with an option to evaluate expressions. When you suspend the execution of an application, you can evaluate expressions. You can define expressions in the Expressions View or evaluate the expressions that are available in the Script Editor. To evaluate an expression, follow these steps: 1. Go to Kony Debug Perspective. 2. Navigate to Window -> Show View -> Expressions. 3. Copy an expression from the required Lua/JavaScript file and paste it in the Expressions View Or click Add an expression to add a new expression in the Expressions View. Note: You cannot perform evaluate expressions in the threads that you suspend manually. 20.9 Debugging an Application You must debug an application to detect and diagnose errors in it. To debug an application 1. Setup your application for debugging. The Kony Debug Perspective window opens and the Application can be viewed on the emulator. 2. From the Debug View, use the execution control command Suspend ( ) button to suspend an executing thread. The thread suspends its execution. The current call stack for the thread is displayed, and the current line of execution is highlighted in the Script Editor. 3. Use the Variables View to view the stack frame's variables and their values. 4. (Optional) Add or remove breakpoints from the Script Editor or from the Breakpoints View. 5. Use the step control debugger operations to step through the execution of an application line-by-line. 6. Resume the execution of the suspended thread from the Debug View by using the Resume ( button. ) Copyright © 2012 Kony, Inc. All rights reserved. Page 687 of 785 Debugging Applications Kony Studio User Guide - 2.1 7. After you complete the debugging, from the Debug View, use the Terminate ( ) button to terminate the debugging on the application. Optionally you can close the emulator to terminate the debug session (not applicable on J2ME). 8. (Optional) If you want to debug the same application on another emulator, from the Navigator View, open the code module of the application that you want to debug. Right-click in the Script Editor and access Debug Configurations from the context menu and select the emulator to debug. Note: All the operations (building applications, adding widgets etc.) that you can perform in the Kony Perspective can also be performed in the Kony Debug Perspective. Once you have switched to the Kony Debug Perspective, you can use it to make changes to your application and debug the application instantly without having to switch back and forth between the Kony Perspective and the Kony Debug Perspective. 20.10 Debugger Behavior while Debugging Mobile Web Applications The following is the debugger behavior while debugging Mobile Web Applications: l l l l l You cannot debug a published Mobile Web Application. If you encounter a Break point during debugging, apart from the standard progress indicator of the browser, there is no other indication on the Mobile Web Application to indicate that the execution is suspended. The result of a statement just executed is not reflected in the UI until the response page is fetched. Closing the browser or navigating to another URL does not terminate an established debug session. To terminate a debug session, use the Terminate option in the Debug View. Terminating a Debug session (by using the Terminate option) does not terminate the Mobile Web Application. The Application continues to run without the debug overhead. Copyright © 2012 Kony, Inc. All rights reserved. Page 688 of 785 Using Command Line Build Kony Studio User Guide - 2.1 21. Using Command Line Build Kony Command Line Build is a tool that assists the build and release teams to build the applications without opening Kony Studio. The settings are stored in build.properties and global.properties files and these settings are used to build the application. You can make appropriate changes in the properties files to build the applications for multiple platforms. Important: Currently, command line build feature is only supported on Windows Operating System. This section comprises the following: l Prerequisites l Configuring Files l Advantages l Building Application l Summary of Steps 21.1 Prerequisites Scenario 1: If you are building the application on a Kony Studio installed system, then you can proceed with Configuring the Command Line Build topic. Scenario 2: If you are building the application on a new system (Kony Studio not installed), then ensure the following folders and files are in place: l Create a New_Folder and check out the project files from the code repository. l From an other system where the Kony Studio is already installed: o Copy the global.properties and ant-contribs.jar files into this New_Folder from the workspace folder. Example path: C:\KONY_Workspace o Copy the build.properties file from the project folder. Example path: C:\KONY_ Workspace\KonyApp o Copy the KonyOne_Studio folder into your system. Example path: C:\KonyOne\KonyOne_Studio l Download and install the following software: o ImageMagick (required for creating gradient artifacts from skin settings in your application for Mobile Web channel) from http://www.imagemagick.org/script/motion-picture.php o Apache Ant v1.8.2 (used for performing ant build) from http://ant.apache.org/bindownload.cgi After the installation, ensure you provide the Environment Variables path to the bin folder of the Apache Ant application. Example path: C:\Program Files\ImageMagick;C:\Ant_1.8.2\bin; Note: Ensure that there is no space in the file or folder names and in its parents folder. Copyright © 2012 Kony, Inc. All rights reserved. Page 689 of 785 Using Command Line Build Kony Studio User Guide - 2.1 Important: The Command Line Build is supported only on Kony Studio 4.1 plugins and above. 21.2 Configuring Files Command Line Build requires the below files to build the applications through command prompt. Note: You do not have to modify the run.bat and build.xml files. l build.properties l global.properties 1. Build.properties: You can make necessary changes to the variables as required. For example, if you have a project in your system in the path C:\Myprojects\releases\SampleApp, you need to have the build.properties file in C:\Myprojects\releases\SampleApp folder. The build.properties file contains the below information. Note: If the values for any variables are left blank, then the values set through Kony Studio are retained while building the application. project.name=<name of the project> #Application details appid=<name of the appID> version=1.0.0 map_google_key= default_locale= android.packagename= #Build app for below platforms iphone=false android=false windows7=false windows6x=false windows_mango=false symbian=false palm=false j2me=false #Blackberry build options Blackberry.All=false Blackberry.JDE7.0.Torch=false Blackberry.JDE7.0.Bold=false Copyright © 2012 Kony, Inc. All rights reserved. Page 690 of 785 Using Command Line Build Kony Studio User Guide - 2.1 Blackberry.JDE7.0.Torch_TouchOnly=false Blackberry.JDE6.0.Torch=false Blackberry.JDE5.0.Storm=false Blackberry.JDE5.0.Bold=false Blackberry.JDE5.0.Pearl3G=false Blackberry.JDE5.0.8800=false Blackberry.JDE4.7.Storm=false Blackberry.JDE4.5.Bold=false Blackberry.JDE4.5.Pearl_8100=false Blackberry.JDE4.5.8800=false Blackberry.JDE4.2.1.Pearl_8100=false Blackberry.JDE4.2.1.8800=false ipad=false androidtablet=false playbook=false html5.iphone=false html5.android=false html5.blackberry=false advanced.nontouch.palm=false advanced.nontounch.html5=false basic_devices=false basic_js=false spa.iphone=false spa.android=false spa.blackberry=false spa.ipad=false spa.androidtablet=false spa.playbook=false wrapper.iphone=false wrapper.android=false hybrid.iphone=false hybrid.android=false #middleware server properties middleware_server_ip= middleware_http_port= middleware_https_port= middleware_web_context=middleware mobileweb_web_context=combo #build mode [release | debug] Copyright © 2012 Kony, Inc. All rights reserved. Page 691 of 785 Using Command Line Build Kony Studio User Guide - 2.1 build.mode=release remove.print.statements=true #If not specified, by default final binaries will be copied to 'binaries' folder inside project binaries.location= 2. global.properties: You can make necessary changes to the variables as required. For example, if you have a project in your system in the path C:\Myprojects\releases, you need to have the global.properties file in C:\Myprojects\releases folder. The global.properties file contains the below information. #Note: Please use '\\' to mention file paths (Ex: C:\\workspace\\project) #Envirnoment details workspace.location=C:\\runtime-EclipseApplication #Full Path to a jar file whose name starts with org.eclipse.equinox.launcher_ in eclipse plugins folder #Example: D:\\eclipse\\plugins\\org.eclipse.equinox.launcher_ 1.1.0.v20100507.jar eclipse.equinox.path=D:\\eclipse-rcp-helioswin32\\eclipse\\plugins\\org.eclipse.equinox.launcher_ 1.1.0.v20100507.jar #preference details imagemagic.home=C:\\Program Files\\ImageMagick-6.3.9-Q16 android.home=D:\\android-sdk-windows run.luaapichecker=false playbook.home=<drive>:\\BlackBerry WebWorks SDK for TabletOS 2.2.0.5 qt.home=<drive>:\\QtSDK palm.home=<drive>:\\Program Files (x86)\\Palm 21.3 Advantages You can build the applications for multiple platforms with a single command. Copyright © 2012 Kony, Inc. All rights reserved. Page 692 of 785 Using Command Line Build Kony Studio User Guide - 2.1 21.3.1 Advantages of a Command Line Build 1. The developer need not open the Kony Studio to build the application. This helps to integrate the compilation and building of Kony Studio projects with "Continuous Build and Integration" tools like Cruisecontrol, Maven, and Hudson. 2. Release management can be handled by a non developer. 3. You can specify the binaries to be copied to a specific location of your choice thus reducing the manual effort of copying the files to a specific location. 4. Ease of Deploying the application on to multiple servers. 21.4 Building Application Below is a scenario of building an application by retrieving the files from a Version Control System such as, SVN. Copyright © 2012 Kony, Inc. All rights reserved. Page 693 of 785 Using Command Line Build Kony Studio User Guide - 2.1 1. Check-Out the project from the SVN to a location on your local system. For example, you have downloaded the project to be built to the location c:\Myprojects\releases\SampleApp 2. Make sure the run.bat, build.xml, and build.properties are present in the project location. For example, c:\myprojects\releases\SampleApp 3. Make sure the global.properties is present in the workspace location. For example, c:\Myprojects\releases 4. Update the global.properties file with the details like workspace location, eclipse.equinox.path and preference details. For example, workspace.location = c:\\Myprojects\\Releases eclipse.equinox.path = c:\\Eclipse_ 4.5\\plugins\\org.eclipse.equinox.launcher_1.1.1.R36x_ v20101122_1400.jar 5. Update the build.properties file with details like project.name, Application details, and platforms that you are building the application for. For more details refer to the section Configuration. 6. Open the command prompt and navigate to the location where the project is available. For example, c:\Myprojects\releases\SampleApp 7. Type ant in the command prompt. You can see the status of the build on the command prompt window. Note: Use the command ant > <drive:\filename> if you want to see the console statements or to monitor the build failures. 8. Once the build is successful, all the binaries are generated at the specified location. Note: All the binary files are copied to binaries folder inside the project folder unless defined in binaries.location in build.properties file. 9. Now Check-In back the project to SVN. 10. The generated project will have the below folder structure if the app is build for Android and Blackberry, unless defined in binaries section of build.properties file. Important: If you are publishing a Thin Client application on the server, follow the prerequisite provided here. Copyright © 2012 Kony, Inc. All rights reserved. Page 694 of 785 Using Command Line Build Kony Studio User Guide - 2.1 21.5 Summary of Steps Building the application through Command Line is easy but at the same time the below things need to be taken care. 1. Ensure you have all the files available mentioned for Command Line Build. 2. Make necessary changes to build.properties file such as project name, application details, middleware server properties, and selection of the required platform. 3. Make necessary changes to global.properties file such as workspace.location, path of eclipse.equinox, android, playbook, qt, palm etc. Note: global.properties file uses \\ in the file paths. For example, c:\\Myprojects\\releases\\SampleApp 4. Always use the build command ant > <drive\<filename>. (For example, ant > c:\Myprojects\buildstatus.txt ) This file contains the command line statements which are used to trace, if the build fails. 5. Always mention the package name, if you are building the application for Android platform. 6. Always cross check the number of platforms you are building for. If you do not wish to build the application for any of the platforms, update the respective platform value as False. 7. It is recommended to use the date in version number, so that you can track when it was last built. Copyright © 2012 Kony, Inc. All rights reserved. Page 695 of 785 Appendix: About the Kony Studio License Kony Studio User Guide - 2.1 22. Appendix: About the Kony Studio License Every working instance of Kony Studio has a valid license. You can choose to deactivate your license from Kony Studio itself. To deactivate your Kony Studio License: 1. In Kony Studio, navigate to Help >About Kony License. The Kony Studio License Information dialog appears. 2. To deactivate the license click Deactivate License. A confirmation dialog appears. 3. To de activate your license, click Yes. To discontinue click No.. 4. A message appears stating that the license has been deactivated. 5. Click OK to close Eclipse. To activate your Kony Studio License: 1. Launch the instance of eclipse for which the license is deactivated. The following message appears. 2. Click Yes to activate the license. 3. Follow the On- screen instructions to update your license. For more information about activating the license, refer the Licensing User Guide. Before License expiry: 1. Launch the Kony Studio. Before viewing the Studio, the following Notification dialog box is displayed when the license validity is lesser than or equal to 30 days. Copyright © 2012 Kony, Inc. All rights reserved. Page 696 of 785 Appendix: About the Kony Studio License Kony Studio User Guide - 2.1 2. Do any one of the following: l l To upgrade your license some other time, click Later. If you have a valid license with you and you wish to upgrade it now, click Yes. The Enter License Details dialog appears. Follow the on screen instructions to upgrade your license. When a license has expired: 1. If your license has expired and you try to launch eclipse, the following dialog appears: 2. Click Yes to activate the license if you have a valid license with you. 3. Follow the onscreen instructions to activate your license. Copyright © 2012 Kony, Inc. All rights reserved. Page 697 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 23. Upgrade Kony Studio This section explains how to upgrade Kony Studio. Before you start make sure: l You are connected to Internet. l Your current licence is still valid to upgrade Kony Studio. l You have valid credentials to access the Kony Developer Portal. Note: If you have already installed Kony Studio by manually copying the plugins to the dropins folder, make sure to delete all the plugins in the dropins folder before upgrading Kony Studio. Note: You can revert to older version if you find some feature is not working as expected after upgrading to the latest version. 23.1 Upgrade to latest version of Kony Studio To upgrade Kony Studio: 1. Open Kony Studio. 2. On the Help menu, click Install New Software. Copyright © 2012 Kony, Inc. All rights reserved. Page 698 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 3. The Install dialog appears. Click Add button in the Work with area. 4. The Add Repository dialog appears. Enter a descriptive name for the update site (such as Kony Updatesite). Enter the following URL in the Location box: http://developer.kony.com/updatesite/50/. Click OK. Click here if you get the below error message. Copyright © 2012 Kony, Inc. All rights reserved. Page 699 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 5. The Login required dialog appears asking for login credentials of the update site. Use your Kony Developer Portal credentials to enter Username and Password and click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 700 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 6. After successful authentication, the Install dialog box re-displays, and shows any available plugins. Note: For example, if you are using 5.0.0.GA plugins and want to upgrade to 5.0.1.GA plugins, but if Kony has already released 5.0.2.GA plugins, then 5.0.2.GA plugins will display. 7. To display all the plugins available for a particular platform, unselect Show only the latest versions of available software. For example, if Android's latest plugin is 5.0.2.GA, then all the plugins 5.0.0.GA, 5.0.1.GA, and 5.0.2.GA will display. 8. Expand each item, select the required plugins and click Next. The Install Details dialog box appears. Review the displayed plugins. You can use the Back button to change the selection. Copyright © 2012 Kony, Inc. All rights reserved. Page 701 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 9. Click Next to continue. If you get an error message as "Cannot complete the install because of a conflicting dependency", click Back button and select all features and click Next. Note: Platform features will have interdependency that may conflict with your existing plugins. In those situations, the error message displays. 10. The Install Review Licenses dialog box appears. Review the Kony Solutions License Agreement. Click I accept the terms of the license agreement and click Finish. Copyright © 2012 Kony, Inc. All rights reserved. Page 702 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 11. The Installing Software window appears showing you the progress of the installation. 12. During the installation process, a Security Warning window appears asking for the authenticity of the software being installed. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 703 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 13. After the installation is completed, a confirmation window appears to restart Kony Studio for the changes to take effect. Click Restart Now to restart Kony Studio. 23.2 Troubleshoot error message While adding repository you may sometimes encounter the below error message. This message occurs when duplicate Locations are entered or login credentials are not entered for location in the first instance. If you get the error message, follow the below steps to resolve: 1. On the Install dialog, click "Available Software Sites" link. Copyright © 2012 Kony, Inc. All rights reserved. Page 704 of 785 Upgrade Kony Studio Kony Studio User Guide - 2.1 2. The Preferences dialog appears. 3. Select the entry from the Available Software Sites and click Remove. Make sure you do not have duplicate entries of the Location. If you still encounter the error message, close Kony Studio and start again. When you solve the error message, continue with step 5. Copyright © 2012 Kony, Inc. All rights reserved. Page 705 of 785 Revert to Previous Configuration Kony Studio User Guide - 2.1 24. Revert to Previous Configuration To revert to the previous plugins of Kony Studio: 1. Open Kony Studio. 2. On the Help menu, click About Kony Studio. 3. The About Kony Studio window appears. Click Installation Details. Copyright © 2012 Kony, Inc. All rights reserved. Page 706 of 785 Revert to Previous Configuration Kony Studio User Guide - 2.1 4. The Kony Studio Installation Details window appears. In the Installed Software tab, the current installed version of Kony Studio is detailed. For example, you can see the plugins version that were upgraded in the above procedure. 5. Click the Installation History tab. The tab displays all the Previous configurations with date and time and the plugins installed during each configuration. Copyright © 2012 Kony, Inc. All rights reserved. Page 707 of 785 Revert to Previous Configuration Kony Studio User Guide - 2.1 6. Select the configuration that you want to rollback and click Revert. 7. A confirmation window appears with a message This operation required restarting the workbench. Would you like to proceed?. Click Yes to proceed. 8. A Login required dialog appears asking for login credentials of the Kony Developer Portal. Enter Username and Password and click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 708 of 785 Revert to Previous Configuration Kony Studio User Guide - 2.1 9. After the process is completed, a confirmation window appears with a message You will need to restart Kony Studio for the changes to take effect. Would you like to restart now? Click Yes to restart Kony Studio. Copyright © 2012 Kony, Inc. All rights reserved. Page 709 of 785 Kony Studio User Guide - 2.1 Appendix: Eclipse Proxy Settings 25. Appendix: Eclipse Proxy Settings Before 5.0.03,the configurations in the following sections are applicable. The following sections provide the proxy settings to be configured on Eclipse. The network preferences are available on the General > Network Connections preference page. Option Description Default Specifies the settings profile to be used when opening connections. Choosing the Native (if Direct provider enables all the connections to be opened without the use of a proxy Active present) server. Selecting Manual causes settings defined in Eclipse to be used. On some Provider Manual platforms there is also a Native provider available, selecting this one causes settings (otherwise) that were discovered in the OS to be used. Proxy The table displays entries that are available for all providers. Checkboxes in the first entries column of the table indicate entries to be used for the currently selected provider. Use this table to specify, either by name or pattern, which hosts should not use any Proxy proxy. A direct connection will always be used for matching hosts. Checkboxes in the bypass first column of the table indicate entries to be used for the currently selected provider. 25.1 Proxy Entries When using Manual proxy provider there are three predefined schemas to set settings for: HTTP, HTTPS and SOCKS [1]. Configuration for each schema is displayed in the Proxy entries table. To edit settings for a particular schema double-click the entry or select the entry and click Edit... button. If Port field is left blank default port number will be used. Following table lists default port numbers for each of the predefined schemas. Schema HTTP SSL SOCKS Default Port 80 443 1080 The SOCKS proxy support in Java 1.4 had certain limitations. Due to these limitations, the setting of the SOCKS system properties is not performed when a 1.4 VM is used. The SOCKS proxy may still be used by some tooling when running on a 1.4 VM (e.g. CVS). However, users should use a 1.5 (or 5.0) VM if they require full SOCKS proxy support. Copyright © 2012 Kony, Inc. All rights reserved. Page 710 of 785 Appendix: Basic or NTLM Proxy Authentication Configuration Kony Studio User Guide - 2.1 26. Appendix: Basic or NTLM Proxy Authentication Configuration If you have NTLM authentication configured at your proxy, you need to add the following configurations for Kony Studio. Before 5.0.03, to add NTLM configurations 1. Navigate to the folder where Eclipse is installed. Eg. D:\eclipse. 2. Edit the file eclipse.ini and add the following lines at the end of the file: -Dkony.proxy.authentication.mode=NTLM -Dkony.proxy.authentication.ntlm.ads.ws=<location of active directory server) #For proxy configurations for Basic and NTML, see Proxy configurations. Important: For a project prior to 5.0 the proxy settings are configured in IDE. For using services created prior to 5.0 in Kony Studio 5.0, enter the proxy details in the eclipse.ini file as stated above. This is a one time configuration only. Here is the sample content of an eclipse.ini file, after adding the above lines: -startup plugins/org.eclipse.equinox.launcher_1.1.0.v20100507.jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_ 1.1.0.v20100503 -product org.eclipse.epp.package.rcp.product --launcher.defaultAction openFile --launcher.XXMaxPermSize 256M -showsplash org.eclipse.platform --launcher.XXMaxPermSize 256m --launcher.defaultAction openFile -vmargs -Dosgi.requiredJavaVersion=1.5 Copyright © 2012 Kony, Inc. All rights reserved. Page 711 of 785 Appendix: Basic or NTLM Proxy Authentication Configuration Kony Studio User Guide - 2.1 -Dkony.proxy.authentication.ntlm.ads.ws=proxytestserv. platformtest.kony.internal -Dkony.proxy.authentication.mode=NTLM Note: If authentication mode attribute is not specified or left empty, the Kony Server falls back to the default authentication mechanism. Note: Once the user is authenticated from the server, the NTLM connection is re-used and the server continues to serve the incoming requests until the password of the user is changed in the Active Directory server. From 5.0.03 onwards, to add Basic or NTLM proxy configurations 1. Navigate to the folder where Eclipse is installed. Eg. D:\eclipse. 2. Edit the file eclipse.ini and add the following lines at the end of the file: # Basic Authentication -Dkony.http.proxyHost=10.0.0.100 -Dkony.http.proxyPort=8800 -Dkony.http.proxyUser=someUserName -Dkony.http.proxyPassword=somePassword # NTLM Authentication -Dkony.proxy.authentication.mode=NTLM -Dkony.proxy.ntlm.domainName=<location of active directory server> Important: You can use either Basic or NTLM Authentication proxy to make the service calls from a proxy environment. For a project prior to 5.0 the proxy settings are configured in IDE. For using services created prior to 5.0 in Kony Studio 5.0, enter the proxy details in the eclipse.ini file as stated above. This is a one time configuration only. Important: For NTLM version 1 ensure that you include the domain name in the username field. For example Domainname/Username or or username@domainname. For NTLM V2 the username field should just include the username. Note: The above Proxy system properties are also applicable to middleware server configuration. Copyright © 2012 Kony, Inc. All rights reserved. Page 712 of 785 Appendix: Deeplink Function Kony Studio User Guide - 2.1 27. Appendix: Deeplink Function Deeplink function allows you to configure the link to a specific form/page of an application, which facilitates navigation to that form directly, bypassing the startup form/homepage. Note: Deeplink function is applicable only for Mobile Web. You can specify the Deeplink function by defining an action sequence for Deeplink Function in Application Properties under Project Properties. Note: For an application there can be only one deeplink sequence/function. Invoke the deeplink function in the Action Sequence for Deeplink Function. 27.1 Working of Deeplink Function By default (when a Deeplink function is not defined/specified), the entry point of the application is the start up form. When a Deeplink function is defined, the entry point of the application is the URL (the specific form) returned by the deeplink function. The parameters that are part of the deeplink URL are saved in a Lua table and passed to the deeplink function (for example, getDeepLink ) as an input parameter. 27.2 Scenarios You need to configure a Deeplink function in the following scenarios: 1. You receive a promotional e-mail with a URL navigating you to the mobile web application of a company. When you click on this promotional URL, you are navigated to a form which is not the start up form of the web application. This way, for different promotions you can be taken to different landing pages. Copyright © 2012 Kony, Inc. All rights reserved. Page 713 of 785 Appendix: Deeplink Function Kony Studio User Guide - 2.1 2. You navigate out of the mobile application to another website, and on completion of some activity you are redirected back to the same page from which you have navigated out. 27.3 Implementation Details The following are the implementation details of a deeplink function: 1. The action sequence defined in Application Properties under Project Properties is executed every time you access the mobile web application. 2. This action sequence is also executed on Mobile Web platform when you access the mobile application website. When the deeplink function is called, the Mobile Web platform implicitly passes a deeplinkcontext. This context is a Lua table with the following information: i. URL with which the application has been accessed. ii. Each of the query parameters associated with that URL. 3. While defining a deeplink function, you should follow the guidelines given below: i. The function should accept a lua table as a parameter. This will allow the platform to pass the deeplink context lua table to the function. ii. The function should always return the form that the user will be navigated to. iii. The function that you are invoking must be returned manually by adding a snippet. Here is an example: If the function you are invoking is launchParams, then the snippet must be defined as: return launchParams(params); Note: Do not invoke form.show within the deeplink function. 27.4 Example For example, if you are searching for flights on a third-party site, you are redirected to the flights details page on selecting a flight. Therefore, you are directly visiting the required page rather than being directed to the home page of the application. This happens when you define a deeplink function. The deeplink URL looks similar to the following: https://www.fltes.com/App/flightDetails?kdeeplink=trueflightNum=UA223&tripType=oneway &leaveDay=20&leaveMonth=Nov&leaveYear=2010 Important: Ensure that the Deeplink URL must contain kdeeplink=true param, if valid user session is already exists. If a deeplink function is not defined, by default, you are directed to the home page of the application. Copyright © 2012 Kony, Inc. All rights reserved. Page 714 of 785 Appendix: Deeplink Function Kony Studio User Guide - 2.1 The deeplink function is similar to the following: function getDeepLink(resulttable) ...print("Deep link table is -->"..resulttable) ...local returnForm = "" ...-- Form to be loaded ...-- Logic to form the main URL ...return returnForm end The print statement in the above function prints the following table: Deep link table is --> [deepLinkPath=/App/flightDetails, flightNum=UA223, tripType=oneway, leaveDay=20, leaveMonth=Nov, leaveYear=2010] The application path in the URL is given by the parameter deepLinkPath (the string before ? excluding the domain name). Form to be loaded ...if resulttable.deepLinkPath == "/App/flightDetails" then .........returnForm=frmFltDetails ...end Logic to form the main URL ...local domain="https://www.fltes.com" -- as this is already known ...local deepLink="" ...deepLink=deepLink..domain ...deepLink=deepLink..resulttable.deepLinkPath ......for i,v pairs in resulttable .........if i~=deepLinkPath then ............deepLink=deepLink..i.."="..v.."&" .........end ......end ...print("The final deeplink is -->"..deepLink) This print statement will print The final deeplink is --> https://fltes.com/App/fltDetails?flightNum=UA223 &tripType=oneway&leaveDay=20&leaveMonth=Nov&leaveYear=2010 Copyright © 2012 Kony, Inc. All rights reserved. Page 715 of 785 Appendix: Appservice Function Kony Studio User Guide - 2.1 28. Appendix: Appservice Function Appservice function allows you to launch and deeplink Kony native applications from any third-party native application and browser application. This feature allows better integration of Kony applications (all native & Mixed Mode applications) with other native and browser based applications. Note: Appservice function is applicable on all platforms. You can specify the Appservice function by defining an action sequence for AppService Function in Application Properties under Project Properties. Note: For an application there can be only one Appservice sequence/function. Invoke the appservice function in the Action Sequence for AppService Function. 28.1 Working of AppService Function By default (when a Appservice function is not defined/specified), the entry point of the application is the start up form. When an AppService function is defined, the form handle returned by appservice is the entry point of the application. The parameters that are part of the URL scheme in the applications are saved in a Lua table and passed to the appservice function. 28.2 Scenarios You need to configure a Appservice function in the following scenarios: 1. You receive an e-mail with a URL that navigates you to the mobile web application of a company. When you click on this promotional URL, you are navigated to a form which is not the start up form of the web application. This way, for different promotions you can be taken to different landing pages. 2. You navigate out of the mobile application to another website, and on completion of some activity you are redirected back to the same page from which you have navigated out. Copyright © 2012 Kony, Inc. All rights reserved. Page 716 of 785 Appendix: Appservice Function Kony Studio User Guide - 2.1 3. When a user receives a link of an application in an email and clicks it, a particular form appears as soon as the application is launched. 28.3 Implementation Details The following are the implementation details of a appservice function: 1. The action sequence defined in Application Properties under Project Properties is executed every time you access an application. 2. The closure provided against appservice will be invoked by the platform in a sequence and this function will also return the form handle. Note: If both postappinit and appservice return the form handle then the form returned by app service is given more priority by the platforms. If both appservice and postappinit return a nil then showstartupform is called. 3. While defining an appservice function, you should follow the guidelines given below: i. The function should always return the form that the user will be navigated to. ii. The function that you are invoking must be returned manually by adding a snippet. Here is an example: If the function you are invoking is launchParams, then the snippet must be defined as: return launchParams(params); Note: Do not invoke form.show within the appservice function. 28.4 Example For example, if you are searching for flights on a third-party site, you are redirected to the flights details page on selecting a flight. Therefore, you are directly visiting the required page rather than being directed to the home page of the application. This happens when you define a appservice function. The appservice URL looks similar to the following: https://www.fltes.com/App/flightDetails?flightNum=UA223&tripType=oneway &leaveDay=20&leaveMonth=Nov&leaveYear=2010 If an appservice function is not defined, by default, you are directed to the home page of the application. The appservice function is similar to the following: function launchParams(params) { //The line below displays how an application is launched: Normal, Copyright © 2012 Kony, Inc. All rights reserved. Page 717 of 785 Appendix: Appservice Function Kony Studio User Guide - 2.1 Push, URL kony.print("*************** params is: "+params); for (var key in params) { kony.print("**********"+params[key]); } kony.print("*************** launch mode is: " + params.launchmode); if(params.launchmode == 1) { labelText = "You have launched this native app from the device."; segData = null; frmMain.segParam.removeAll (); return frmIntro; }else if(params.launchmode == 3){ labelText = "You have launched this kony native app from a third party app."; //Displays the launchparams. The Launchparams table is a table with key value pairs specific to the applications needs; kony.print("*************** launch params are: " + params. launchparams); if(params.launchparams != null){ segData = [ ]; for ( k in params.launchparams ){ var v = params.launchparams[ kony.decrement( k ) ]; kony.print("key:" + k + "value:" + v); kony.table.insert(segData, { lblkey : "" + k + " :", lblval : "" + v } ); } labelText = labelText + "The Parameters are:"; }else{ kony.print("*************** launchparams is nil"); } return frmMain; } return frmIntro; } The application path in the URL for iPhone and Android is given by the URL scheme. For more information about URL scheme refer to Native Application Properties. For BlackBerry deeplinking is done through Service Identifiers For Windows 7.5, you can launch and deeplink Kony native applications from any third-party native application and browser application using Cards. Unlike other applications, deeplinking in Windows 7.5 opens an application from a Bing Browser.For more information about setting cards, refer Windows Manifest File. You can also deeplink applications using secondary tiles. For Windows 8 the Deeplinking occurs solely through secondary tiles using a code like the snippet below. Copyright © 2012 Kony, Inc. All rights reserved. Page 718 of 785 Appendix: Appservice Function Kony Studio User Guide - 2.1 function onPostappInitDl(params) { kony.print("post app init"); kony.print(params); if(params.launchMode == 2) { var x = params.launchParams; if(x.tileId == "myTile1") { return form2; } } }; For more information about setting secondary tiles refer Kony API Reference Guide. Copyright © 2012 Kony, Inc. All rights reserved. Page 719 of 785 Appendix: Generating and Configuring Map API Keys Kony Studio User Guide - 2.1 29. Appendix: Generating and Configuring Map API Keys You will need Maps API Key for Maps to work in the applications you develop. You need to generate the Maps API key and specify it in the properties of the Map widget. You need to configure the following map keys for your application: l Application Level Map widget key (generic key at application level for J2ME, MobileWeb, Blackberry devices which do not support BlackBerry Maps) l Google Map key for Android (exclusive key for Android platform). l Bing Map key for Windows 29.1 Application Level Map Widget Key The map widget key needs to be generated based on a domain name. The key generated for a single domain can be used for all sub-domains, URLs on hosts in those domains, and all ports on those hosts. For more information about the domain to be used for generating a map APIs key, see http://code.google.com/apis/maps/faq.html#keysystem. The generated map key is configured at an application level. This map key is used by all the Map widgets within an application. This map key enables the application to display Google Maps through the Map widgets within the application. To configure map widget key, follow these steps: 1. Go to https://code.google.com/apis/console and log in with your Google Account. i. Click the Services link from the left-hand menu. ii. Activate the Google Maps API v3 service. iii. Note the API Key that you generate. iv. Click the API Access link from the left-hand menu. Your API key is available on the API Access page, in the Simple API Access section. Maps API applications use the Key for browser apps. By default, a key can be used on any site. We strongly recommend that you restrict the use of your key to domains that you administer, to prevent use on unauthorized sites. You can specify which domains are allowed to use your API key by clicking the Edit allowed referrers... link for your key. 2. Go to Applications View. 3. Right-click the required application and select Properties. 4. Enter the API Key you have generated in the Static map widget key field under Map widget. Copyright © 2012 Kony, Inc. All rights reserved. Page 720 of 785 Appendix: Generating and Configuring Map API Keys Kony Studio User Guide - 2.1 5. Click Finish. A Clean and Rebuild window appears as shown below: 6. Click OK. The application gets built on the platforms that were selected earlier in the Build Generation window. Note: When you add a Map widget to a form, the map widget key you have entered in step 4 automatically appears against Google Map Key property of the Map widget. The key generated once is applicable to all the Map widgets within an application. This configured map widget key is applicable for all platforms except for Android. For Android you need to generate a specific map APIs key and use it in the properties. For more information, see Google Map Key for Android. 29.2 Google Map Key for Android You need the Google Maps API key for Android in order to enable Maps in the applications you develop for Android platform. Maps API keys are linked to specific certificate/package pairs, rather than to users or applications.You only need one key for each certificate, no matter how many users you have for an application. Applications that use the same certificate can use the same API key. For generating maps API key for Android, you need to provide the fingerprint of the signed certificate. For more information about signing Android applications, see http://developer.android.com/guide/developing/eclipse-adt.html and https://developers.google.com/maps/documentation/android/start?hl=en Copyright © 2012 Kony, Inc. All rights reserved. Page 721 of 785 Appendix: Generating and Configuring Map API Keys Kony Studio User Guide - 2.1 Important: Version 1 of the Google Maps Android API as been officially deprecated as of December 3rd, 2012. This means that from March 3rd, 2013 you will no longer be able to request an API key for this version. No new features will be added to Google Maps Android API v1. However, apps using v1 will continue to work on devices. Existing and new developers are encouraged to use Google Maps Android API v2. To configure Google Maps API Key v2 for Android, follow these steps: 1. Please follow steps for Display your app's certificate information and Create an API project in the Google APIs Console under link Getting the Google Maps Android API v2. 2. Once you are done with Create an API project in the Google APIs Console, make sure you turn on "Google Maps Android API v2" service under Services section in Google API console. Note: In case of redirection to Cloud Console use this link for older Google API console: https://code.google.com/apis/console/?noredirect. 3. To get the key, navigate to the Google API console: l In the left navigation bar, click API Access. l In the resulting page, click Create New Android Key.... l In the resulting dialog, enter the SHA-1 fingerprint, then a semicolon, then your application's package name. For example:BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75;com.example.an droid.mapexample 4. The Google APIs Console responds by displaying Key for Android apps (with certificates) followed by a forty-character API key, for example: AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0 5. Navigate to Properties > NativeApp > Android > Tags > Child tag entries under <application> Copyright © 2012 Kony, Inc. All rights reserved. Page 722 of 785 Appendix: Generating and Configuring Map API Keys Kony Studio User Guide - 2.1 tag. Add the following tag <meta-data android:name="com.google.android.maps.v2.API_KEY" android:value="Map V2 key"/>. Replace the value of the Map V2 key with the generated Map v2 key. Important: Google Play services Revision 13 (Version Name 4.0.30 released on November 2013) and newer versions require Android 2.3 or higher. 6. If you have Google Play Services older to v13 you do not have to perform this step. If you have downloaded Google Play services v13 in Android SDK manager, follow either of the step: a. To support Android v2.2 and above devices: i. Download Google Play services for Froyo from the Android SDK manager. ii. Rename the folder "google_play_services_froyo" to "google_play_ services", in the Android SDK path: ..\android-sdk- windows\extras\google\. b. If you want to use the latest Google Play libraries (Rev 13 and above which supports only Android v2.3 and above devices): i. In Kony Studio, navigate to Properties > NativeApp > Android > Tags > Child tag entries under <application> tag. ii. Add the following tag: <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />. Important Considerations: l Google Maps V2 does not work on an emulator. l Multiple Map widgets per Form is not supported.(Both MapV1 and V2). l l l If MapV2 key is provided in IDE and if the application is installed on a device with Android Verison 2.2 and above (i.e kony.os.deviceInfo().APILevel >= 8 ) Google Maps Version 2 would be loaded by default. In rest all cases Google Maps Version 1 would be loaded. If the developer uses Google Maps V2, the developer must meet the Google Play attribution requirements as specified at https://developers.google.com/maps/documentation/android/intro#attribution_requirements . The attribution text is available by using kony.os.deviceInfo().googleplayservicesoftwarelicence in Lua and kony.os.deviceInfo().googleplayServiceSoftwareLicence in JavaScript projects respectively . This property returns the open source software license information for the Google Play services application, or null when either Google Play services is not available on this device or MapV2 Key is not added in application properties. Map does not work on a popup. Copyright © 2012 Kony, Inc. All rights reserved. Page 723 of 785 Appendix: Generating and Configuring Map API Keys l Map preview launches only version 1 map l Map V2 works for Android 2.2 and above. l l l l Kony Studio User Guide - 2.1 Clickable/Interactive widgets inside a Map callout template will become non-clickable when Android Map V2 version is used. This is the limitation of native Android Map V2 callout. As callouts are displayed as static image snapshot of callout template and only the entire callout is clickable. onSelection event callback is invoked when a callout is clicked. You need to update the "Android SDK Tools"," Android SDK Platform-tools" to the latest revision using under SDK Manager (Min revision of Android SDK Tools required is >=15 for Android Google MapV2). Android Google MapsV2 requires OpenGL ES version 2 to load. You need to download the latest Google Play Services sdk using the SDK Manager. To do so, navigate to Extras > Google Play Services. Please refer to the links below for additional information on how Android Google Play and Google MapsV2 work o http://developer.android.com/google/play-services/index.html o http://developer.android.com/google/play-services/setup.html o http://developer.android.com/google/play-services/maps.html 29.3 Bing Map Key for Windows To generate a Bing Map Key for Windows platforms, refer http://msdn.microsoft.com/enus/library/ff428642.aspx. Navigate to Application>Properties and enter the obtained key in the Bing map widget key field. Copyright © 2012 Kony, Inc. All rights reserved. Page 724 of 785 Appendix: Handling Form Factors for Different Platforms Kony Studio User Guide - 2.1 a Copyright © 2012 Kony, Inc. All rights reserved. Page 725 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms 30. Appendix: Handling Form Factors for Different Platforms The general look, size, and shape of a mobile device is collectively known as Form Factor. You can add different images for different form factors on mobile devices. 30.1 Android Smartphone/Tablet Platform Resources specific to Android platform and specific to a locale/screensize/orientation/resolution should follow the below mentioned instructions. You should create the following folders in the resources/mobilerichclient/android/ folder: l l drawable-<language>-r<Region> when you have resources specific to locales only. For example, if you want to add a resource for en_US locale, then create a drawable-en-rUS folder and place the resource in drawable-en-rUS folder. drawable-<screensize> when you have resources specific to screen size only. Possible screen sizes are small, normal, large, and xlarge. For example, if you want to add a resource for normal screen size, then create a drawable-normal folder and place the resource in drawable- normal folder. l drawable-<orientation> when you have resources specific to orientation only. Possible values for orientation are land and port. For example, if you want to add a resource for landscape orientation, then create a drawable-land folder and place the resource in drawable- land folder. l drawable-<screen-pixel-density> when you have resources specific to resolution or screen-pixel-density only. Possible values for screen-pixel-density are ldpi, mdpi, hdpi, xhdpi, and nodpi. For example, if you want to add a resource for hdpi pixel density, then create a drawable- hdpi folder and place the resource in drawable-hdpi folder. Important: In Kony IDE, if you specify an app icon for Android with a name other than icon.png, it will not pickup the images present in the Android specific resources folders (drawable-mdpi, drawable-xdpi, etc.). To mitigate this keep your app icon image in the common folder. If you have resources specific to a combination of these factors then you must follow precedence rules and name the folders appropriately. The precedence rules are as follows: 1. locales/language and region 2. screen size 3. orientation 4. screen pixel density. The following table explains a few examples: Folder drawable-en-rUS-land Description resources specific to US-English devices in landscape mode Copyright © 2012 Kony, Inc. All rights reserved. Page 726 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms Folder drawable-port-hdpi drawable-en-rUS-largeland drawable-en-rUS-largeland-hdpi Description resources specific to devices in portrait mode with hdpi pixeldensity resources specific to US-English large screen devices in landscape mode resources specific to US-English large screen devices in landscape mode with hdpi density Android 1.5 and lower versions do not support the following configuration qualifiers: l Density/screen-pixel-density : ldpi, mdpi, hdpi, and nodpi l Screen size: small, normal, and large. This following table helps you in creating the resource folders as per screen size categories: Image folder name drawable-small drawable-normal (diagonal screen size) drawable-large Approximate Size Remarks 2" - 3.5" 3" - 4.5" This is the baseline size. 4.1" - 7" Introduced in Android 2.3 to anticipate tablets. drawable-xlarge 7" - 10.5" Important: To add this folder, ensure that you select the target SDK Version as Android 2.3 (API level 9) in the IDE Project Properties window. This following table helps you in creating the resource folders as per screen density (dpi) categories: Image folder name drawable-ldpi drawable-mdpi drawable-hdpi Approximate resolution ~120 dpi ~160 dpi ~240 dpi Remarks this is the baseline density on android platform Added in API Level 8 (Android 2.2). drawable-xhdpi ~320 dpi drawable-nodpi NA Important: To add this folder, ensure that you select the target SDK Version as Android 2.3 (API level 9) in the IDE Project Properties window. resources for images that should not be scaled on different density screens Copyright © 2012 Kony, Inc. All rights reserved. Page 727 of 785 Appendix: Handling Form Factors for Different Platforms Kony Studio User Guide - 2.1 30.1.1 How to Calculate DPI dpi = sqrt((width res * width res) + (height res * height res)) / (diagonal screen size in inches) For example, for a device with 480X854 resolution and screen size of 4.1 inch diagonal, the dpi = sqrt(480x480 + 854x854)/4.1 = 239 i.e., ~240 dpi. The folders created based on the screen density serve majority of the devices available in the market. But if you want to provide specific resource when running on, say a device with normal screen and high dpi, create a directory with combination of screen size and density like drawable-normal-hdpi and place the image here. "Screen size" categories take a priority than the "Screen density". If you provide images within, say "drawable-large" and "drawable-hdpi" folders and if the device falls under both large and hdpi category, then Android system will give preference to screen size i.e., "drawable-large". Note: The drawable-## folders must be created under <project>/resources/mobilerichclient/android folder. 30.1.2 Add Resource Folders Kony IDE also provides option to create the above mentioned. 1. Right click resource/mobilerichclient/android folder under Applications View. 2. Select the appropriate ooption in the Add Android Resources Folder window. 3. Click OK. A new folder gets created under resources/mobilerichclient/android based on the options you select in the above step. For example, the folders like drawable, drawable-small, and so on are created. For more information about device categories, see http://developer.android.com/guide/practices/screens_ support.html. The following is a list of supported devices for Android Native App platform along with the corresponding form factors: Device/Family HTC Dream (T-Mobile G1) HTC Magic (T-Mobile myTouch) HTC Hero (T-Mobile G2, Droid Eris) HTC Tattoo Motorola DROID Google Nexus One Motorola Cliq Samsung Moment SPHM900 Samsung Galaxy Tab Form Factor 320x480 320x480 320x480 320x240 480x854 480x800 320x480 320x480 1024x600 Copyright © 2012 Kony, Inc. All rights reserved. Page 728 of 785 Appendix: Handling Form Factors for Different Platforms Kony Studio User Guide - 2.1 30.2 Android and Blackberry Mobile Web/ SPA Platform For Android and BlackBerry (thin client and SPA platform) the support for target density has been enhanced from the current release onwards to include a further level of granularity in terms of the image resources and font sizes used. Android Mobile Web /SPA The change was primarily necessitated with some of the discrepancies being observed in devices with respect to the device density meta tags. One of the symptoms was that in some devices the screen was getting zoomed when focused on a textbox. To handle such issues we have reworked our approach towards picking up the right images by adding a few additional image sizes (360, 400, 440). As of 4.1, we still support the older mechanism of image handling even if no images are provided in the 360, 400, 440 categories. From 5.0 onwards it is mandatory for all the applications to provide images in the 360, 400, 440 structures for an application to work. Important: If there is no resource present in the folder for 360, 400, 440 dpi, the application picks up images from the previously supported folder structures. Please note that with the changes made, the 240, 320, 640 folders are not required. But have been retained to support older versions of the applications. The supported folder structure for target density was as follows: l 240 l 320 l 640 SPA and Mobile web support a new mechanism where the target density is no more used in case of Android and BlackBerry. From the current release onwards the folder structure supported is: l 360 l 400 l 440 New resources for the application have to be provided by the developer. Copyright © 2012 Kony, Inc. All rights reserved. Page 729 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms 1. Devices with dpi ratio<=1 will pick assets from 360 category 2. Devices with dpi ratio<=1.5 will pick assets from 400 category 3. Devices with dpi ratio<=2 will pick assets from 440 category To ensure that the dpi folder changes are reflected, follow these steps: l Eclipse should open in clean mode. l Run upgrade actions. l Workspace web-app folder should delete before clean build. BlackBerry - Mobile Web/SPA In BB and BB non-touch devices,though images were getting picked from respective 320/480/640 asset folders,there were issues observed like images either appearing larger in size or not fitting to screen. A consistent solution has been provided to overcome such issues by introducing: - 360 and 400 categories for BB and BBnth. - Default base fonts being 13 and 14 for 360 and 400 categories respectively. - Availability of background-size property under forked button skin when background image spills beyond the screen. 30.3 BlackBerry Platform BlackBerry platform is available on mobile devices with different form factors. The platform varies in features depending on the JDE version on the device. Therefore, two different devices with same model can vary in features (software only), because these devices have a different version of JDE. BlackBerry platform has different form factors as shown in the following table: Model Name BlackBerry BlackBerry BlackBerry BlackBerry BlackBerry Bold BlackBerry Bold BlackBerry Bold BlackBerry Bold BlackBerry Bold BlackBerry Bold BlackBerry Curve Model Number 8800 8820 8830 9650 9000 9700 9780 9790 9900 9930 8300 Screen Resolution (width*height) 320X240 320X240 320X240 480X360 480X320 480X360 480x360 480x360 640x480 640x480 320X240 Device Category MEDIUM MEDIUM MEDIUM LARGE LARGE LARGE LARGE LARGE LARGE LARGE MEDIUM Touch/Nontouch Non-touch Non-touch Non-touch Non-touch Non-touch Non-touch Non-touch Both Both Both Non-touch Copyright © 2012 Kony, Inc. All rights reserved. Page 730 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve BlackBerry Curve Torch BlackBerry Pearl Flip BlackBerry Pearl BlackBerry Pearl BlackBerry Pearl BlackBerry Pearl BlackBerry Pearl Flip BlackBerry Style Flip BlackBerry Storm2 BlackBerry Storm BlackBerry Storm BlackBerry Tour BlackBerry Torch BlackBerry Torch BlackBerry Torch BlackBerry Torch BlackBerry Playbook 8310 8320 8330 8350i 8500 8520 8530 8900 9330 9350 9360 9370 320X240 320X240 320X240 320X240 320X240 320X240 320X240 480X360 320x240 480x360 480x360 480x360 MEDIUM MEDIUM MEDIUM MEDIUM MEDIUM MEDIUM MEDIUM LARGE MEDIUM LARGE LARGE LARGE Non-touch Non-touch Non-touch Non-touch Non-touch Non-touch Non-touch Non-touch Touch Non-touch Non-touch Non-touch 9380 360x480 STORM Touch 8220 240X320 SMALL Non-touch 8100 8110 8130 8120 240X260 240X260 240X260 240X260 SMALL SMALL SMALL SMALL Non-touch Non-touch Non-touch Non-touch 8230 240X320 SMALL Non-touch 9670 480x360 LARGE Non-touch 9550 9530 9520 9630 9800 9810 9850 9860 360x480 360x480 360x480 480X360 360x480 480x640 480x800 480x800 STORM STORM STORM LARGE STORM(6.0) STORM(7.0) STORM(7.0) STORM(7.0) Touch Touch Touch Non-touch Both Both Touch Touch 1024x600 MEDIUM Touch Kony Studio generates different binaries for different JDE versions. The binaries are different for different form factor categories within a JDE version. Copyright © 2012 Kony, Inc. All rights reserved. Page 731 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms Kony Studio generates the following COD files for the following form factors: Device 4.2.1 Nontouch devices (but less than 4.5) 4.2.1 Nontouch devices (but less than 4.5) 4.2.1 Nontouch devices (but less than 4.5) 4.5 Nontouch devices (but less than 5.0) 4.5 Nontouch devices (but less than 5.0) 4.5 Nontouch devices (but less than 5.0) Category SMALL (pearl) COD File ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry/dist/small-appid-bbrel.cod ../<<workspacename>>/temp/<<appname>>/buil MEDIUM (8800) d/ luaj2me/blackberry/dist/appid-bb-rel.cod LARGE LARGE device is not available for versions earlier than 4.5 SMALL (pearl) ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry/dist/45-small-appid-bbrel.cod ../<<workspacename>>/temp/<<appname>>/buil MEDIUM (8800) d/ luaj2me/blackberry/dist/45-appid-bb-rel.cod LARGE (8900,9000) ../<<workspacename>>/temp/<<appname>>/build /blackberry/dist/large-appid-bb-rel.cod Copyright © 2012 Kony, Inc. All rights reserved. Page 732 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms Device Category COD File 5.0 and above Non-touch devices Note: You need this device only when SMALL you are using 5.0 specific features like Push, Auto Complet e Field, Custom Fonts. SMALL device is not available for 5.0 Copyright © 2012 Kony, Inc. All rights reserved. Page 733 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms Device Category COD File 5.0 and above Non-touch devices Note: You need this device only when MEDIUM (8800) you are using 5.0 specific features like Push, Auto Complet e Field, Custom Fonts. ../<<workspacename>>/temp/<<appname>>/build /luaj2me/blackberry/dist/50-appid-bbrel.cod Copyright © 2012 Kony, Inc. All rights reserved. Page 734 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms Device Category COD File 5.0 and above Non-touch devices Note: You need this device only LARGE when (8900,9000,9350, you are 9360,9370) using 5.0 specific features like Push, Auto Complet e, Field, Custom Fonts. 4.7 Touch devices ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry/dist/50-large-appid-bbrel.cod ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-47rel.cod Copyright © 2012 Kony, Inc. All rights reserved. Page 735 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms Device Category COD File 5.0 and above Touch devices Note: You need this device only when you are using 5.0 specific features like Push, Auto Complet e Field, Custom Fonts. 6.0 Touch (Torch) STORM (9800) Device 7.0 Touch (Curve) STORM (9380) Device 7.0 Touch STORM (9850 (Torch) and 9860) Devices 7.0 Touch (Torch) STORM (9810) Device 7.0 Touch (Bold LARGE (9790) Touch) Device ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-50storm.cod ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-60storm-rel.cod ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-70storm-rel.cod ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-70touchonly-rel.cod ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-70torch-rel.cod ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-70largetouch-rel.cod Copyright © 2012 Kony, Inc. All rights reserved. Page 736 of 785 Kony Studio User Guide - 2.1 Appendix: Handling Form Factors for Different Platforms Device Category 7.0 Touch (Bold LARGE (9900 Touch) and 9930) Devices COD File ../<<workspacename>>/temp/<<appname>>/buil d/ luaj2me/blackberry47/dist/appid-bb-70boldtouch-rel.cod Based on the above screen configurations, the BlackBerry platform uses the resources placed in the directories mentioned in the following table: Device Category Directory Name mobilerichclient/blackberry/small mobilerichclient/blackberry mobilerichclient/blackberry/large l mobilerichclient/blackberry/storm SMALL MEDIUM LARGE STORM l mobilerichclient/blackberry/torch70 for Torch 9810 device mobilerichclient/blackberry/pearl3g (260x400) PEARL3G for 9100 device Note: The directory names are case-sensitive. Important: The BlackBerry application picks up images from mobilerichclient/blackberry folder by default. If you want different images to be used based on the screen resolutions of the mobile devices, create images with the same name (as that of mobilerichclient/blackberry folder) in the corresponding folders and override the images to suit the screen resolution. For example, to use different images for small screen resolutions, create images in the folder mobilerichclient/blackberry/small with the same names as that have been used in the mobilerichclient/blackberry folder. 30.4 iPhone/iPad/iPod Platform The following is a list of supported devices for iPhone/iPad/iPod Native App platform along with the corresponding form factors: Device/Family iPhone 2G iPhone 3G iPhone 3GS iPod (1G) iPod (2G) iPod (3G) iPhone 4 iPad Form Factor 320x480 320x480 320x480 320x480 320x480 320x480 320x480 768x1024 Copyright © 2012 Kony, Inc. All rights reserved. Page 737 of 785 Appendix: Handling Form Factors for Different Platforms Kony Studio User Guide - 2.1 30.5 J2ME Platform The following is a list of supported devices for J2ME Native App platform along with the corresponding form factors: Device/Family Nokia E50 Nokia E61 Nokia E66 Nokia E70 Nokia N90 Nokia N72 Nokia 5310 Xpressmusic Nokia 5610 Xpressmusic Nokia 8800 Nokia 9500 Motorola RAZR V9 Motorola ROKR E6 Motorola A780 LG HB620 LG KF750 LG KG800 Samsung S8000 Samsung SGH i900 Samsung SGH D900i Samsung SGH D800 Sanyo SCP M1 Sony Ericsson X2 Sony Ericsson U1i Sony Ericsson Z750i Sony Ericsson W902 Sony Ericsson K630i Sony Ericsson C510 Panasonic VS7 Orange SPV M2000 Alcatel OT-708 Form Factor 240x320 320x240 240x320 352x416 352x416 176x208 240x320 240x320 208x208 640x200 240x320 240x320 240x320 320x240 240x320 176x220 480x800 240x320 240x320 240x320 240x260 800x480 360x240 240x320 240x320 176x220 240x320 320x240 240x320 240x320 Note: Some of the devices have limited memory capabilities and support a Light version with limited screens and low resolution images only. Copyright © 2012 Kony, Inc. All rights reserved. Page 738 of 785 Appendix: Handling Form Factors for Different Platforms Kony Studio User Guide - 2.1 30.6 Windows Mobile 7 Platform The following is a list of supported devices for Windows Mobile 7 Native App platform along with the corresponding form factors: Device/Family Dell Venue Pro (AT&T coming soon) HTC HD7 (T-Mobile) HTC 7 Mozart (coming soon to carriers) HTC Surround (AT&T) HTC 7 Trophy(coming soon to carriers) LG Optimus 7(coming soon to carriers) LG Quantum/Optimus 7Q(AT&T) (coming soon to carriers) Samsung Focus (AT&T) Samsung Omnia 7(coming soon to carriers) Form Factor 480x800 480x800 480x800 480x800 480x800 480x800 480x800 480x800 480x800 Note: From Release 2.0, the IDE does not support Windows Mobile Standard/Professional 6.0/6.1/6.5 versions. 30.7 Palm Pre Platform The following is a list of supported devices for Palm Pre Native App platform along with the corresponding form factors: Device/Family Palm Pre Palm Pre Plus Palm Pixi Palm Pixi Plus Form Factor 320x480 320x480 320x400 320x400 For more information about Palm Pre devices, see http://www.phonearena.com/phones/Palm-Pixi-PlusGSM_id4657 and http://www.phonearena.com/phones/Palm-Pre-Plus_id4347. 30.8 Symbian/MeeGo Platform The following is a list of supported devices for Nokia S60 Edition: Device/Family C5-03 5250 5228 C6-00 Form Factor 360x640 360x640 360x640 360x640 Copyright © 2012 Kony, Inc. All rights reserved. Page 739 of 785 Appendix: Handling Form Factors for Different Platforms Device/Family 5230 Nuron 5235 Ovi Music unlimited N97 mini X6-00 5230 5530 XpressMusic N97 5800 XpressMusic Kony Studio User Guide - 2.1 Form Factor 360x640 360x640 360x640 360x640 360x640 360x640 360x640 360x640 The following is a list of supported devices for Maemo: Device/Family N900 N810 WiMAX N810 N800 Form Factor 800x480 800x480 800x480 800x480 The following is a list of supported devices for Symbian: Device/Family N8-00 E7-00 C7-00 C6-01 Form Factor 360x640 640X360 640x360 360X640 Copyright © 2012 Kony, Inc. All rights reserved. Page 740 of 785 iPad Orientations Kony Studio User Guide - 2.1 31. iPad Orientations Just like an iPhone device, iPad also supports both Landscape and Portrait orientation modes. However unlike iPhone, in iPad most often all the forms in the application either will be in portrait or in landscape or respect both the orientations. It is also possible that individual forms will have orientations different from the rest of the application. Kony platform offers a simple mechanism to have explicit control over the orientation mode when the application is launched and its following screens. This control is driven by 3 specific properties in the Kony Studio: 1. Application Launch Mode for iPad: This specifies the orientation mode that needs to be locked when the first screen of the application is shown to the user. Note: Ensure that the Application Launch Mode for iPad and the displayOrientation property for the Start Up form do not contradict each other i.e the Start up form can support more orientations compared to the launch mode orientation but should not contradict . For e.g. If the Application Launch Mode for iPad is set to Portrait , the displayOrientation for the Start Up form should be FORM_DISPLAY_ORIENTATION_PORTRAIT or FORM_DISPLAY_ ORIENTATION_BOTH but cannot be set as FORM_DISPLAY_ORIENTATION_LANDSCAPE. .For e.g. If the Application Launch Mode for iPad is set to Landscape , the displayOrientation for the Start Up form should be FORM_DISPLAY_ORIENTATION_LANDSCAPE or FORM_DISPLAY_ ORIENTATION_BOTH but cannot be set as FORM_DISPLAY_ORIENTATION_PORTRAIT. .For e.g. If the Application Launch Mode for iPad is set to Both , the displayOrientation for the Start Up form should be FORM_DISPLAY_ORIENTATION_BOTH, and cannot be set as either FORM_ DISPLAY_ORIENTATION_BOTH ,or FORM_DISPLAY_ORIENTATION_LANDSCAPE. Copyright © 2012 Kony, Inc. All rights reserved. Page 741 of 785 Kony Studio User Guide - 2.1 iPad Orientations 2. Supported Orientations for iPad: This specifies the orientation modes that should be supported through out the application. This essentially dictates the orientation super set that is applicable at the application level and individual forms can only have orientation values within the super set. Any value configured at the form level outside the super set are not respected. 3. displayOrientation (Form level property): This specifies the orientation mode in which the form should be displayed. The above properties provide you with the extreme flexibility to control the orientation modes that application should support. The table below indicates the various combinations of orientation settings and the expected behaviors. Application Launch mode for iPad(Application properties in IDE) Start up Form Orientation Portrait Landscape Both Portrait Portrait Landscape Both Portrait Landscape Landscape . Both Portrait Landscape Both Portrait Both Landscape Both Expected application behavior on launch Launched as Portrait and the application remains in the Portrait mode. Not recommended. Behavior is undefined on application launch. Not recommended. Behavior is undefined on application launch. Launched in Portrait and the further forms will change based on the orientations specified in the form properties. Not recommended. Behavior is undefined on application launch. Not recommended. Behavior is undefined on application launch. Not recommended. Behavior is undefined on application launch. Launched in Landscape and the further forms will change based on the orientations specified in the form properties Not recommended. Behavior is undefined on application launch. Not recommended. Behavior is undefined on application launch. Launched as Landscape and the application remains in the Landscape mode. Not recommended. Behavior is undefined on application launch. Not recommended. Behavior is undefined on application launch. Not recommended. Behavior is undefined on application launch. Launched in both portrait, landscape. Form will rotate depending on the device orientation. Copyright © 2012 Kony, Inc. All rights reserved. Page 742 of 785 Frequently Asked Questions about iPad Orientation (FAQs) Kony Studio User Guide - 2.1 32. Frequently Asked Questions about iPad Orientation (FAQs) I want to lock my application in landscape mode from the time it is launched , how to achieve that? Ensure that the orientation on both Application Launch Mode for iPad and the Supported Orientations for iPad should be set as Landscape. Deselect the Portrait checkbox. I want to lock my application in portrait mode from the time it is launched , how to achieve that? Ensure that the orientation on both Application Launch Mode for iPad and the Supported Orientations for iPad should be set as Portrait. Deselect the Landscape checkbox. I want to lock my application in landscape mode but the forms are to be displayed as per the displayOrientation property to set at the Form level, how to achieve that? Ensure that the Application Launch Mode for iPad should be set as landscape, the Supported Orientations for iPad should be set as both. Set the displayOrientation property of the form to the approriate value. Copyright © 2012 Kony, Inc. All rights reserved. Page 743 of 785 Frequently Asked Questions about iPad Orientation (FAQs) Kony Studio User Guide - 2.1 I want to lock my application in portrait mode but the forms are to be displayed as per the displayOrientation property to set at the Form level, how to achieve that? Ensure that theApplication Launch Mode for iPadshould be set as portrait,Supported Orientations for iPadshould be set a both. Set the displayOrientation property of the form to the appropriate value Copyright © 2012 Kony, Inc. All rights reserved. Page 744 of 785 Appendix: BlackBerry MDS Kony Studio User Guide - 2.1 33. Appendix: BlackBerry MDS The BlackBerry Mobile Data System (MDS) is an application development framework that offers wireless connectivity to the applications. It is a component of the BlackBerry Enterprise Server, and uses standardsbased methods and protocols for integrating wireless applications with existing applications. The BlackBerry MDS Services include the following components: l l BlackBerry MDS Integration Service - this service allows the BlackBerry MDS applications to interact with the back-end systems through web services or direct database connections. You can install BlackBerry MDS Integration Service when you install the BlackBerry Enterprise Server. BlackBerry MDS Connection Service - this service processes requests for web content from the BlackBerry Browser or from BlackBerry Java Applications. For more information about BlackBerry MDS, see http://docs.blackberry.com/en/admin/deliverables/7335/BB_MDS_267706_11.jsp. Copyright © 2012 Kony, Inc. All rights reserved. Page 745 of 785 Appendix: Profiler Kony Studio User Guide - 2.1 34. Appendix: Profiler The Profiler provides the performance analysis of an application which is developed using the Kony Studio. It recognizes all Lua method calls and the Kony API calls as well. The profiler is applicable only on Lua projects. The Profiler tracks the following: l Number of times a particular method or a Kony API is invoked l The time taken to execute a Lua method or the Kony API Note: The time taken for execution includes the time taken to execute any sub-sequent method calls. l The free and total memory available to the application at the time of beginning of the execution of a lua method and ending of a Lua method or a Kony API. When you exit/close the application, a summary is provided which states the total time taken by the application. Note: The Profiler itself uses some memory to track the application performance (however, the memory usage compared to the application's memory consumption is relatively small and it tracks application performance if the application is running on the foreground. Note: The Profiler itself takes some time to capture the statistics . However, this time is accounted for by the profiler and does not affect the output time reported for a particular Lua method or a Kony API. However, the total execution time as displayed by the profiler does differ by a small amount since the profiler execution time is not accounted for. 34.1 Profiler Setup for iOS After building the application and launching Xcode execute the following: Copyright © 2012 Kony, Inc. All rights reserved. Page 746 of 785 Appendix: Profiler Kony Studio User Guide - 2.1 1. In the Xcode dialog navigate to Product>Edit Schemes. Note: If the Edit Scheme option is disabled, navigate to Product> Manage Schemes, select a scheme, and click OK to proceed. 2. Select the scheme you want to edit. Copyright © 2012 Kony, Inc. All rights reserved. Page 747 of 785 Appendix: Profiler Kony Studio User Guide - 2.1 3. To add a command line parameter, in the Arguments Passed on Launch area, click . 4. Add a command line parameter of the format -p<outputfilename>. In the example in the image, the output filename provided is profiler.txt. 5. Click OK. Copyright © 2012 Kony, Inc. All rights reserved. Page 748 of 785 Appendix: Profiler Kony Studio User Guide - 2.1 Once you run and launch the application on the emulator, the profiler tool launches when the application is launched and tracks the application data. A sample output on a Profiler for iPhone would look something like, (N) >> funcname: (X) (C) (free/total) (MEMF/MEMT) (N) << funcname: (Rms) (free/total) (MEMF/MEMT) Each component in the sample code snippet are as follows: l N(number): Indicates the call level. l >>: Indicates that a function is being called. l <<: Indicates that the exit of a function. l funcname: Name of the function being called or exited. Copyright © 2012 Kony, Inc. All rights reserved. Page 749 of 785 Appendix: Profiler l (X): Indicates if the function is a Lua method or a Kony API. For a Lua API X is replaced by an L and for a Kony API X is replaced by a K. On iPhone the X will be denoted only by a K since all the Luacode is converted into bytecode for iOS. l (C): Indicates the number of times a function is called. l (MEMF): Indicates the free memory on the device. l Kony Studio User Guide - 2.1 (MEMT): Indicates the total memory on the device. The difference between MEMT and MEMF is used to calculate the memory used by the application or a method. 34.2 Profiler Setup for Android To setup the profiler on Android, build the application for android and execute the following: 1. Launch the SDK Manager. 2. Navigate to Tools>Manage AVDs. The AVD Manager appears. 3. Select an AVD name and click the Edit button, and add a value in for the SD Card size field. Important: It is important to specify a size in the SD Card field since if the field is empty, when the profiler is launched, an error occurs. 4. Ensure that you have set the WRITE_EXTERNAL_STORAGE permission to true in the Android Manifest file. For more information on accessing the Android Manifest file, refer Android Manifest. 5. Click Window -> Preferences. 6. Click Kony Dev Studio in the left panel. The Kony Studio Preferences panel appears on the right side of the window. 7. Select Always Profile Application, this enables you to profile an application. Copyright © 2012 Kony, Inc. All rights reserved. Page 750 of 785 Appendix: Profiler Kony Studio User Guide - 2.1 8. Within Kony Studio, navigate to Window> Show View > Other. The Show View dialog appears. 9. Type Profiler in the textfield provided. 10. Select Profiler and click OK. The Profiler for Android appears. 11. Launch the application on the emulator. 12. Click on the Start form in IDE and in the Profiler view, click Start Profiler A sample output on a Profiler for Android would look something like, . (N) >> funcname: (X) (C) (free/total) (MEMF/MEMT) (N) << funcname: (Rms) (free/total) (MEMF/MEMT) Each component in the sample code snippet are as follows: Copyright © 2012 Kony, Inc. All rights reserved. Page 751 of 785 Appendix: Profiler l N(number): Indicates the call level. l >>: Indicates that a function is being called. l <<: Indicates that the exit of a function. l funcname: Name of the function being called or exited. l (X): Indicates if the function is a Lua method or a Kony API. For a Lua API X is replaced by an L and for a Kony API X is replaced by a K. l (C): Indicates the number of times a function is called. l (MEMF): Indicates the free memory on the device. l Kony Studio User Guide - 2.1 (MEMT): Indicates the total memory on the device. The difference between MEMT and MEMF is used to calculate the memory used by the application or a method. If you run the application for the first time, the profiler may not be able run since 'profiler_com.kony.txt' file may not be present in the AVD for the first time. The following error will be seen in the command prompt for android. cannot create /sdcard/profiler_com.kony.txt: read-only file system So, the user will have to run the application again so that the next time the profiler picks up the file and start logging into it. 34.3 Profiler Setup for BlackBerry To setup the profiler on BlackBerry, build the application for BlackBerry and execute the following: 1. Build an Application and launch an emulator. 2. Navigate to Simulate > Change SD Card. The SD Card dialog appears. 3. Mount a directory. This operation mounts a directory and this directory is used as an SD card for that emulator. 4. In the mounted directory create a profiler.txt file. 5. Launch the application. 6. A sample output in the profiler.txt file for BlackBerry would look something like, (N) >> funcname: (X) (C) (free/total) (MEMF/MEMT) (N) << funcname: (Rms) (free/total) (MEMF/MEMT) Note: If you use the same directory to mount the SDCard, for multiple applications, the profiling information for the new application is appended to the same profiler.txt file. Each component in the sample code snippet are as follows: l N(number): Indicates the call level. Copyright © 2012 Kony, Inc. All rights reserved. Page 752 of 785 Appendix: Profiler l >>: Indicates that a function is being called. l <<: Indicates that the exit of a function. l funcname: Name of the function being called or exited. l (X): Indicates if the function is a Lua method or a Kony API. For a Lua API X is replaced by an L and for a Kony API X is replaced by a K. On iPhone the X will be denoted only by a K since all the Luacode is converted into bytecode for iOS. l (C): Indicates the number of times a function is called. l (MEMF): Indicates the free memory on the device. l Kony Studio User Guide - 2.1 (MEMT): Indicates the total memory on the device. The difference between MEMT and MEMF is used to calculate the memory used by the application or a method. Copyright © 2012 Kony, Inc. All rights reserved. Page 753 of 785 Appendix: Sample URL Provider for Service Definition Kony Studio User Guide - 2.1 35. Appendix: Sample URL Provider for Service Definition The following is a sample URL Provider for the Service Definition file: import java.net.MalformedURLException; import java.net.URL; import java.util.HashMap; import org.apache.log4j.Logger; import com.konylabs.middleware.controller.DataControllerRequest; public class TestURLProvider implements com. konylabs.middleware.common.URLProvider { ...public String execute(String urlStr, DataControllerRequest request) ...{ ...//Write application logic to modify the URL string here ...// return the modified URL string here ...return endpointUrlStr; ...} } a Copyright © 2012 Kony, Inc. All rights reserved. Page 754 of 785 Appendix: Sample Skin.xml File Kony Studio User Guide - 2.1 36. Appendix: Sample Skin.xml File The following is a sample skin.xml file: <skins> ...<skin> ......<att name="Name" value="gradroundbtn" type="String"/> ......<att name="WidgetType" value="Button" type="String"/> ......<att name="Bg_type" value="1" type="int"/> ......<att name="Background_color" value="255,255,255" type="RGB"/> ......<att name="Rightbackground_color" value="255,255,255" type="RGB"/> ......<att name="Bg_gradient_style" value="0" type="int"/> ......<att name="Rightbg_gradient_style" value="0" type="int"/> ......<att name="Background_gradient_top_color" value="255,255,255" type="RGB"/> ......<att name="Background_gradient_bottom_color" value="150,190,255" type="RGB"/> ......<att name="Rightbackground_gradient_top_color" value="255,255,255" type="RGB"/> ......<att name="Rightbackground_gradient_bottom_color" value="255,255,255" type="RGB"/> ......<att name="Background_gradient_top_colorSet" value="1" type="int"/> ......<att name="Background_gradient_bottom_colorSet" value="1" type="int"/> ......<att name="Background_image" value="" type="String"/> ......<att name="Right_background_image" value="" type="String"/> ......<att name="Bg_iphone_image" value="" type="String"/> ......<att name="Bg_android_image" value="" type="String"/> ......<att name="Bg_palm_image" value="" type="String"/> ......<att name="Bg_normal_image" value="" type="String"/> ......<att name="Bg_medium_image" value="" type="String"/> ......<att name="Bg_small_image" value="" type="String"/> ......<att name="Bg_bb_image" value="" type="String"/> ......<att name="Bg_winmobile_image" value="" type="String"/> ......<att name="Bg_iphoneiui_image" value="" type="String"/> ......<att name="Bg_j2me_image" value="" type="String"/> ......<att name="Bg_symbian_image" value="" type="String"/> ......<att name="Bg_ipad_image" value="" type="String"/> Copyright © 2012 Kony, Inc. All rights reserved. Page 755 of 785 Appendix: Sample Skin.xml File Kony Studio User Guide - 2.1 ......<att name="Bg_android_rc_tablet_image" value="" type="String"/> ......<att name="Bg_adviphone_image" value="" type="String"/> ......<att name="Bg_adv_bb_image" value="" type="String"/> ......<att name="Bg_advpalm_image" value="" type="String"/> ......<att name="Bg_advandroid_image" value="" type="String"/> ......<att name="Bg_advother_image" value="" type="String"/> ......<att name="Bg_js240_image" value="" type="String"/> ......<att name="Bg_js320_image" value="" type="String"/> ......<att name="Bg_js480_image" value="" type="String"/> ......<att name="Font_weight" value="normal" type="String"/> ......<att name="Font_style" value="none" type="String"/> ......<att name="Font_size" value="100" type="String"/> ......<att name="Font_color" value="0,0,0" type="RGB"/> ......<att name="Font_color_alpha" value="0" type="String"/> ......<att name="Rightfont_weight" value="normal" type="String"/> ......<att name="Rightfont_style" value="" type="String"/> ......<att name="Rightfont_size" value="100" type="String"/> ......<att name="Rightfont_name" value="None" type="String"/> ......<att name="Border_color" value="141,185,250" type="RGB"/> ......<att name="Border_width" value="1" type="Integer"/> ......<att name="Border_style" value="1" type="int"/> ......<att name="Bg_img_style" value="0" type="int"/> ......<att name="Bg_one_color_style" value="0" type="int"/> ......<att name="Platform" value="0" type="int"/> ......<att name="arcRadius" value="0" type="int"/> ......<att name="Stretch_image" value="false" type="Boolean"/> ......<att name="Repeat_image" value="false" type="Boolean"/> ......<att name="Bg_height" value="15" type="Integer"/> ......<att name="CustomCss" value="false" type="Boolean"/> ......<att name="Split_value" value="50" type="String"/> ......<att name="Bg_alpha" value="0" type="String"/> ......<att name="Bg_top_alpha" value="0" type="String"/> ......<att name="Bg_bottom_alpha" value="0" type="String"/> ......<att name="Right_bg_alpha" value="0" type="String"/> ......<att name="Right_bg_top_alpha" value="0" type="String"/> ......<att name="Right_bg_bottom_alpha" value="0" type="String"/> ......<att name="Border_color_alpha" value="0" type="String"/> ......<att name="PgIndicatorImgURL" value="null" type="String"/> ......<att name="PgIndicatorImgPositon" value="null" type="String"/> Copyright © 2012 Kony, Inc. All rights reserved. Page 756 of 785 Appendix: Sample Skin.xml File Kony Studio User Guide - 2.1 ......<att name="PgIndicatorImgWidget" value="Button" type="String"/> ......<att name="BlockingImgURL" value="null" type="String"/> ......<att name="BlockingImgPositon" value="null" type="String"/> ......<att name="BlockingImgWidget" value="Button" type="String"/> ......<att name="TopBorderWidth" value="0" type="int"/> ......<att name="TopBorderColor" value="0,0,0" type="RGB"/> ......<att name="TopBorderColorTransparency" value="0" type="int"/> ......<att name="TopBorderStyle" value="null" type="String"/> ......<att name="TopBorderRadius" value="10" type="int"/> ......<att name="LeftBorderWidth" value="0" type="int"/> ......<att name="LeftBorderColor" value="0,0,0" type="RGB"/> ......<att name="LeftBorderColorTransparency" value="0" type="int"/> ......<att name="LeftBorderStyle" value="null" type="String"/> ......<att name="LeftBorderRadius" value="10" type="int"/> ......<att name="BottomBorderWidth" value="0" type="int"/> ......<att name="BottomBorderColor" value="0,0,0" type="RGB"/> ......<att name="BottomBorderColorTransparency" value="0" type="int"/> ......<att name="BottomBorderStyle" value="null" type="String"/> ......<att name="BottomBorderRadius" value="10" type="int"/> ......<att name="RightBorderWidth" value="0" type="int"/> ......<att name="RightBorderColor" value="0,0,0" type="RGB"/> ......<att name="RightBorderColorTransparency" value="0" type="int"/> ......<att name="RightBorderStyle" value="null" type="String"/> ......<att name="RightBorderRadius" value="10" type="int"/> ......<att name="ApplicablePlatforms" value="111111111111111111" type="String"/> ......<att name="UseNative" value="false" type="Boolean"/> ......<att name="Font_color_override" value="false" type="Boolean"/> ......<att name="Font_name_override" value="false" type="Boolean"/> ......<att name="Font_size_override" value="false" type="Boolean"/> ......<att name="Font_style_override" value="false" type="Boolean" /> ......<att name="Font_weight_override" value="false" type="Boolean" /> ....</skin> </skins> Copyright © 2012 Kony, Inc. All rights reserved. Page 757 of 785 Appendix: GPS Functionality Kony Studio User Guide - 2.1 37. Appendix: GPS Functionality GPS stands for Global Positioning System. The GPS uses satellites to transmit precise microwave signals. The mobile devices with GPS receivers derive the current location, time, and velocity of the device from the signals. GPS functionality has the following three main components: l Absolute location - determines the location of the user l Relative movement - useful in applications related to Seismology and Astronomical Sciences l Time transfer - clock synchronization that enables time transfer. These components determine the current position of the user based on the following factors: l Cellular ID l Longitude l Latitude. GPS functionality is useful in the following scenarios: l Commerce - to locate a nearby ATM or a hotel l Scientific Uses - to determine planetary movements l Tracking - vehicle tracking l Surveillance. Kony Studio has implemented the GPS functionality using W3C standards. As per the W3C standards, the HTML 5.0 tags allow the web browsers within an application or a browser on a mobile device to directly access and use the location data. Kony Studio provides you the option of enabling an application to use the GPS functionality, which internally uses the HTML 5.0 tags to fetch the current location data. 37.1 Supported Platforms on Mobile Web Mobile Web supports GPS functionality for the following platforms: l iPhone l Android l BlackBerry l Palm. 37.2 Process for Capturing Location Details You must specify that the application should capture the location details by selecting Requires GPS under Mobile Web Properties. Copyright © 2012 Kony, Inc. All rights reserved. Page 758 of 785 Appendix: GPS Functionality l l l l l l Kony Studio User Guide - 2.1 The location details are obtained using the Javascript APIs supported by the web browsers. Set Capture GPS property for the form on which you want to capture the GPS details. For more information about this property, see Kony Widget User Guide. When you set the above mentioned property on a form, the application displays a popup seeking permission from the user to access the location details. If the user cancels this popup, an error with error code 102 (Location API access is denied by user) is thrown. This error can be handled by the application. If the user allows the popup, the Javascript API is executed which captures the location details of the application. These details are updated on the kony Application Server. The details updated on the Kony Application Server are returned when phone.mylocation API is invoked on the device. For more information about phone.mylocation API, see Kony API Reference Guide. Copyright © 2012 Kony, Inc. All rights reserved. Page 759 of 785 iWay Enterprise Connectors Kony Studio User Guide - 2.1 38. iWay Enterprise Connectors Kony Studio now enables you to integrate iWay Enterprise Connectors. iWay Connectors enable developers to build Web and wireless applications which access information from different applications or databases. iWay Connectors enable you to write an application without writing custom-coded interfaces and making multiple calls across different environments. The iWay Connector sends application requests on the iWay superhighway, where iWay adapters transform and optimize these requests for a desired data source and return the required output to the iWay connector. The iWay connector then passes on the desired output to the requesting application. iWay Connectors can be used for standard industry interfaces, including ODBC, JDBC, XML, ActiveX/DCOM, and OLE/DB. For other enterprise application integration projects, other connectors can plugand-play with third-party application servers, Java Virtual Machines (JVMs), or messaging systems such as IBM's WebSphere, MQSeries, and MQSeries Integrator. Once these services are exposed, you can import these services by using the services available in the Kony Studio. iWay Connectors provide standard interface like Soap/Web Services/RESTful for enterprise systems. Kony connectors present in Studio / Server will communicate with iWay Soap/Web Services/RESTful services. For more information on iWay connectors refer, http://www.iwaysoftware.de/products/iWay_connectors.html Copyright © 2012 Kony, Inc. All rights reserved. Page 760 of 785 Appendix: web.xml Kony Studio User Guide - 2.1 39. Appendix: web.xml When you build an application for Mobile Web, a WAR (Web archive) file is generated. The WAR file contains a web.xml file that defines the web application structure. The Mobile Web platform follows the J2EE specifications for structuring the WAR file. The WAR file structure is as illustrated by the image below: Apart from the folders listed under platform specific folders, the android, bb, bjs, iphone, palm, and win folders contain JS and CSS files. The WAR file structure also contains the WEB-INF folder which contains the web.xml file. The WEB-INF folder structure is as illustrated by the image below: Copyright © 2012 Kony, Inc. All rights reserved. Page 761 of 785 Kony Studio User Guide - 2.1 Appendix: web.xml The platform specific folders contain the JSP files. The scripts folder contains the .o file (lua byte code file). The web.xml file defines the web application structure. The web.xml file has the following parameters: Parameter Required Yes for Jetty and Preview modes DefaultServlet Not for Publish mode Description This parameter is used for mapping the default Servlet in Jetty. Specifies the controller file that intercepts the incoming request when mapped to a requesting path. Based on the mode, the mapping varies as follows: KonyWebController Yes l Jetty and Preview modes: The mapping is done to the URL pattern /p. Publish mode: The Servlet is mapped to /p, /p/*, and /. Based on your requirement, you can choose to map it to any other pattern. Indicates the Application name. This parameter is populated automatically during the build process. Specifies if the device db must be looked up for device detection. Depending upon the mode, the default value changes as follows: l appid Yes device_db_lookup Yes l Jetty and Preview modes: false (because the db is not available locally on the Jetty server. Publish mode: true Specifies the non-secure port on which the server is running. This information is used to construct the URL for redirections. Specifies the secure port on which the server is running. This information is used to construct the URL for redirections. l httpport Yes httpsport Yes Copyright © 2012 Kony, Inc. All rights reserved. Page 762 of 785 Kony Studio User Guide - 2.1 Appendix: web.xml Parameter Required Description Indicates the type of session used by the application. session_type Yes From the project properties of the application in the IDE, you can specify the Session Manager as Kony Session Manager or Http Session Manager. Based on your selection, this parameter is populated automatically by the IDE during the build process with the following values: l 0 - Indicates that the session manager is Kony Session Manager. 1 - Indicates that the session manager is Http Session Manager. Specifies the https port on which the request must be received. This parameter is equivalent of getLocalPort on the server (when the Web Server is behind a load balancer). Based on the mode, the parameter value differs as follows: l sechtno Yes l Jetty and Preview modes: The port number specified in the httpsport parameter is used. Publish mode: This parameter is not a part of the web.xml file, but is included in the Tomcat web.xml or their equivalents in the WEBLOGIC or WEBSPHERE. Specifies the comma separated list of application locales supported by the current application. The application locales specified in the IDE are populated during the build process. This information is used to load locale specific resources during the application initialization. Indicates the location of the JSP files. This information is populated automatically during the build process. Depending upon the location, the value of this parameter varies as follows: l applocales Yes jsp_base Yes l / - if the JSP files are under the web folder. /WEB-INF/ - if the JSP files are under the WEBINF folder. This listener is part of the application initialization. This listener is used to verify if the middleware properties have been provided and also to verify if the deviceDetectionLogic.xml file is placed in the correct middleware folder. l com.konylabs. middleware.common .AppContextListener Yes Copyright © 2012 Kony, Inc. All rights reserved. Page 763 of 785 Kony Studio User Guide - 2.1 Appendix: web.xml Parameter com.kony.web.util. TCValidationListener Required Yes Yes for Publish Mode Description This listener is part of the application initialization. This listener is used to verify if the deviceDetectionLogic.xml file is placed in the correct middleware folder. This filter is used for handling browser back button in advanced devices. Based on the session manager you have specified in the IDE, this parameter is included in the web.xml or commented out. KonyHistoryFilter No for Jetty and Preview modes l l Yes for Jetty and Publish Modes MiddlewareDCFilter No for Preview mode Yes for Publish Mode Error Handler If the Session Manager is Kony Session Manager : This parameter is included in the web.xml. If the Session Manager is Http Session Manager : This parameter is commented out. Indicates the middleware filter that is called during the Mobile Web request processing. Specifies the customized error.jsp page that must be displayed when an error or exception is encountered by the application. This parameter is required only in Publish mode. No for Jetty and Preview modes middleware_interface Yes region Yes In local Jetty mode, when the application is run in debug mode, the errors are displayed on the browser with a full stack trace. This is a context parameter and it specifies if the application must make a remote call to services to fetch the data or if the data is locally co-located as in EJBLocal. In Jetty mode, the value of this parameter is remote while in the Publish mode it is local. This parameter enables you to reduce procuring more number of application server licenses.It facilitatse more number of middleware versions on the same JVM/app server node. The following is a sample web.xml file: <?xml version="1.0" encoding="UTF-8"?> <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"> <!-- This parameter is used for mapping the default Servlet in Jetty. This parameter is not relevant for publish environments Copyright © 2012 Kony, Inc. All rights reserved. Page 764 of 785 Appendix: web.xml Kony Studio User Guide - 2.1 --> <servlet> <servlet-name>DefaultServlet</servlet-name> <servlet-class>org.mortbay.jetty.servlet.DefaultServlet</servletclass> </servlet> <servlet-mapping> <servlet-name>DefaultServlet</servlet-name> <url-pattern>/</url-pattern> </servlet-mapping> <servlet> <!-- Specifies the controller file that intercepts the incoming request when mapped to a requesting path. Based on the mode, the mapping varies as follows: 1) Jetty and Preview modes: The mapping is done to the URL pattern /p. 2) Publish mode: The Servlet is mapped to /p, /p/*, and /. Based on your requirement, you can choose to map it to any other pattern. --> <servlet-name>KonyWebController</servlet-name> <servletclass>com.kony.web.controller.KonyWebWAPController</servlet-class> <!--Indicates the Application name. This parameter is populated automatically during the build process. --> <init-param> <param-name>appid</param-name> <param-value>{appid}</param-value> </init-param> <init-param> <param-name>servletname</param-name> <param-value>p</param-value> </init-param> <!--Specifies if the device db must be looked up for device detection. Depending upon the mode, the default value changes as follows: 1)Jetty and Preview modes: false (because the db is not available locally on the Jetty server. 2) Publish mode: true --> <init-param> <param-name>device_db_lookup</param-name> <param-value>false</param-value> </init-param> <!--Specifies the non-secure port on which the server is running. This information is used to construct the URL for redirections. --> Copyright © 2012 Kony, Inc. All rights reserved. Page 765 of 785 Appendix: web.xml Kony Studio User Guide - 2.1 <init-param> <param-name>httpport</param-name> <param-value>{httpport}</param-value> </init-param> <!--Specifies the secure port on which the server is running. This information is used to construct the URL for redirections. --> <init-param> <param-name>httpsport</param-name> <param-value>{httpsport}</param-value> </init-param> <!--Indicates the type of session used by the application. From the project properties of the application in the IDE,you can specify the Session Manager as Kony Session Manager or Http Session Manager. Based on your selection, this parameter is populated automatically by the IDE during the build process with the following values: 0 - Indicates that the session manager is Kony Session Manager. 1 - Indicates that the session manager is Http Session Manager. --> <init-param> <param-name>session_type</param-name> <param-value>{session_type}</param-value> </init-param> <!--Specifies the https port on which the request must be received. This parameter is equivalent of getLocalPort on the server (when the Web Server is behind a load balancer). Based on the mode, the parameter value differs as follows: 1) Jetty and Preview modes: The port number specified in the httpsport parameter is used. 2) Publish mode: This parameter is not a part of the web.xml file, but is included in the Tomcat web.xml or their equivalents in the WEBLOGIC or WEBSPHERE. --> <init-param> <param-name>sechtno</param-name> <param-value>{httpsport}</param-value> </init-param> <!--Specifies the comma separated list of application locales supported by the current application. The application locales specified in the IDE are populated during the build process. This information is used to load locale specific resources during the application initialization. --> <init-param> <param-name>applocales</param-name> <param-value>{locales}</param-value> </init-param> Copyright © 2012 Kony, Inc. All rights reserved. Page 766 of 785 Appendix: web.xml Kony Studio User Guide - 2.1 <!--Indicates the location of the JSP files. This information is populated automatically during the build process.Depending upon the location, the value of this parameter varies as follows: / - if the JSP files are under the web folder. /WEB-INF/ - if the JSP files are under the WEB-INF folder. --> <init-param> <param-name>jsp_base</param-name> <param-value>{jsp_base}</param-value> </init-param> </servlet> <!-- These are Servlet mappings --> <servlet-mapping> <servlet-name>KonyWebController</servlet-name> <url-pattern>/p</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>KonyWebController</servlet-name> <url-pattern>/p/*</url-pattern> </servlet-mapping> <session-config> <session-timeout>">
/
Download
Just a friendly reminder. You can view the document right here. But most importantly, our AI has already read it. It can explain complex things in simple terms, answer your questions in any language, and help you quickly navigate even the longest or most compilcated documents.
Public link updated
The public link to your chat has been updated. You may view and manage your chat links after registration here.
Document public link
Advertisement
Key features
Rapid mobile application development and deployment
Visual development environment with Form Designer
Extensive library of pre-built widgets
Device-independent wire-frame design
Customizable platform-specific properties for native look and feel
Direct and secure backend data integration with Kony Platform
Testing on device emulators and quick/automatic preview
Lua/JavaScript scripting environment for complex functionality
Debugging capabilities for applications
Frequently asked questions
Kony Studio is an integrated development environment (IDE) provided as a plug-in to Eclipse for the rapid development and deployment of mobile applications.
Kony Studio supports Lua/JavaScript for scripting, offering a powerful scripting environment optimized for mobile environments.
Kony Studio facilitates direct and secure communication with existing client data systems, allowing you to define data connections once and apply them across all devices without migrating data.
