Skip to Content

SAP Web IDE has included a template which allows you to create a Hybrid Mobile Extension Project.  This feature can be used to mobilize Fiori applications allowing you to utilize the extensibility concept. This concept allows you to modify the workings of an application without actually changing the parent, the SAP delivered, app’s code.  In this blog we will walk through the project structure to understand the structure and where modifications could be made.

If you haven’t already done so you will first need to enable the HAT plugin and for building projects setup the Hybrid Application Toolkit.  Information regarding these topics can be found in the help and in SAP Web IDE Mobile.  To just enable the template you can simply just enable HAT Plugin by selecting Tools -> Preferences -> Option Plugins and enabling com.sap.webide.hybrid.  Restart the browser after saving your changes.

You can start by creating a new Hybrid Mobile Extension Project by choosing New -> Hybrid Mobile Extension Project.  In the first step choose your Remote system and select the desired app and then choose Next and Finish to complete the process.


Screen Shot 2015-10-09 at 9.30.26 AM.png

The Project Structure


After generation you will notice that the app structure looks similar to a standard Fiori extension app.  In addition, the template has generated a hybrid and webapp directory.  As normal, the Component.js acts as a Fiori app’s main entry point as well as containing any extension declarations.  Taking a look at this file you will notice that the file loads the app to be extended, using the “sap.ui.component.load” call, by referencing the property “sap.hybrid.ParentAppUrl”.  This property is defined in the file hybrid/sap-mobile-hybrid.js as a url, allowing the app to reference the ui code on the backend during design time.  When choosing to build/deploy the app, HAT will then pull the parent app code from the backend and place it into the project.  This process enhances the user’s experience by improving load time by eliminating the need to for a data connection to download all of the required files.  Only the actual data sources will be called when the app is loaded.

The index.html allows us to run the app on a mobile device, on a browser as a stand alone app or within the launchpad sandbox.  What differentiates this file from a non mobile app is the use of the sap-mobile-hybrid.js and the cordova.js.  The cordova.js provides us access to native device features such as the camera as well as the ability to use features provided by SMP/HCPms.  These options are both configured by right clicking on the project and choosing Project Settings -> Device Configuration and then choosing the desired plugin.

The file sap-mobile-hybrid.js, found on the root level of the hybrid folder, contains a bootStrap function which is called from the index.html handling the main aspects of the initial loading of the app. This function determines, based off of the environment and a set of configurable parameters, how the app is to be ran.  This includes determining if we are running on a desktop vs a device or the companion app as well as the HCPms/SMP configuration functionality.  It also initializes a few objects necessary if the use of SMP/HCPms is desired.  Once the configuration is determined, the file hybrid/odata/hybridodata.js is then loaded.  This file contains helper functions to obtain the appropriate odata service and to handle any authentication method that may be needed.

In the hybrid directory we will also find a few subfolders with the first being kapsel.  Inside this folder you will find the file logon.js.  This file contains all of the necessary code to assist in the use of the kapsel login plugin which allows users to register to HCPms/SMP.  The only necessary step to utilize this plugin is to enable the plug itself in the device configuration of the project, which can be found by right clicking on the project and choosing Project Settings -> Device Configuration.


In the hybrid/odata/hybridodata.js the function “sap.hybrid.initSMPOfflineOData” is defined to initialize the definition of the offline store.  The call to this function originates from the bootstrap function of the sap-mobile-hybrid.js file.  To offline an app, the existence of one or more defining requests is necessary.  A defining request object determines what Collection(s) of an OData service are to be offlined.  For further explanation please visit Getting Started with Kapsel – Part 15 — Offline OData (New in SP05).  This object can be defined in the SAP delivered app manifest.json or within the hybrid extension’s app manifest.json.  This file is know as the app description and contains many other important declarations such as version and configuration information.  By default the code in the bootStrap function of sap-mobile-hybrid.js looks in the parentapp’s manifest, but this can be easily changed to the extension app.  This would be declared in the manifest in the following manner…



"sap.app":{
     ...
     "offline": true
},
"sap.mobile": {
    "_version": "1.1.0",
    "definingRequests": {
            "WorklistCollectionDr" : {
                "dataSource": "SRA008_SRV" ,
                "path": "/WorklistCollection"
            }
        }
  }











For an expanded app descriptor example please see Descriptor for Applications, Components, and Libraries


Also take note that the function sap.hybrid.initSMPOfflineOData in the hybridodata.js is expecting that the Cordova device and network are enabled in addition to the Kapsel odata.

The coding that handles the management of the offline store is defined in hybrid/odata/offlinestore.js.  When using offline functionality, the syncing of changes occurs by flushing the local changes to the backend and then refreshing the backend changes to the offline store.  This can be achieved by adding a control to your app to call the function pushAppOfflineStore which exists in the offlinestore.js file. 


To proceed with making modifications to the app, choose the menu option File -> New -> Extension and follow the guided process.  If you are new to this concept please visit SAP Web IDE – Advanced.


Regards,

Jamie Cawley


To report this post you need to login first.

8 Comments

You must be Logged on to comment or reply to a post.

  1. Gavin Quinn

    Hi Jamie — awesome overview, thanks.

    One concept I can’t quite follow. A lot of assumptions are made in various configuration steps that we are using either HCPms or SMP. I presume creating a Hybrid Extension app with this method will also work through HCP html5 app?

    Screen Shot 2016-04-27 at 8.34.34 PM.png

    After tweaking the Component.js file after the deployment to find the parent’s Component.js file I can get the app to run:

    Screen Shot 2016-04-27 at 8.36.13 PM.png

    However, I don’t get any data back. I would presume that if I’m routing through HCP html5 app, I should get prompted for my cloud identity at some point?

    Otherwise, if I want to use oauth2, or basic auth to another endpoint, where would I override the logon methods?

    Selecting the Kapsel Logon plugin, again presumes I am using HCPms or SMP.

    Thoughts?

    (0) 
    1. Jamie Cawley Post author

      Where do you have the parent app, is that also on hcp or on premise?  How do you have the destination setup?  If your backend connection is set to no authentication, you can try setting the app itself to not require authentication and the backend should prompt you. See

      SAP HANA Cloud Platform

      Regards,

      Jamie

      (0) 
      1. Gavin Quinn

        Thanks Jamie — inline:


        Where do you have the parent app, is that also on hcp or on premise?


        On-premise transactional app. I did validate though that the parent app gets pulled properly during the publishing process.



        How do you have the destination setup? 


        Just a gateway destination with basic auth — that could be the problem?


        If your backend connection is set to no authentication, you can try setting the app itself to not require authentication and the backend should prompt you.


        Good point — but doesn’t that sort of “break” the security model, by allowing end-users access all the way down to sap on-premise un-authenticated?


        The main issue is the html5 app on hcp itself should require / prompt for the username / password (i would guess) similar to what happens when you launch the app with a web browser. However, since it’s just a service call, it probably doesn’t provide the “pop-up” window to do that. I would think the most optimal method would be OAUTH2 against HCP, but curious where I would set that in the hybrid extension app, since it assumes Logon is only for HCPms or SMP?

        (0) 
        1. Jamie Cawley Post author

          Yes, the kapsel logon plugin is only for hcpms.  The point for setting the authentication to none is for testing purposes.  Once you can confirm that it is working then I would work on setting up as desired, saml or principle propagation.

          Regards,

          Jamie

          (0) 
  2. Giel Janssen Lok

    Great blog Jamie,

    I have an app that is build using WEB IDE template

          “templateId”: “ui5template.emptyMobileProjectKapsel”,

          “templateVersion”: “1.4.0”,

    This does not have the folders Hybrid, and web app. It also does not have the Device configuration option in the WEB IDE Menu (only if i activate it via the project properties)

    When I deploy my current app to HAT and build build kapsel app, it does not run correctly. it’s relative services etc point to local android path.

    Is this structure you describe here, mandatory for all Kapsel apps or only when you want to extend an app?


    Regards,

    (0) 
    1. Jamie Cawley Post author

      Hi Giel,

      This blog is specific to the Hybrid Mobile Extension Project which has changed since this has been published.  The current version of the template you are using is 1.28 so I am not sure what has changed.   I would suggest opening a new discussion thread regarding your issue if you can not solve it.

      Regards,

      Jamie

      (0) 
      1. Peter Vanneste

        Any news on this one?

        i also used this template and no hybrid folder was created.

        When i deploy the extension project using hat, i get:

        get project zip encountered error: cannot read property ‘kapsel’ of undefined

        i suppose this is related, correct?

        what has changed in this template?

        thanks

        (0) 

Leave a Reply