One of the new less talked about features in SAP HANA SP6+ I would say is the concept of the XS Application Site. It is still under development for the platform and is far from being perfect however if you look past the current limitations to what it could/will grow to be, you will find an excellent tool that encourages good development practices and has the potential to bring structure to what can be chaos.
What is a SAP HANA XS Application Site (App Site)
In a nutshell it is a container for mini web pages. Rather than developing an entire site with dependencies between the various components, you instead develop mini chunks of functionality called widgets. Widgets are put into the app site container to make up your finished website.
Let’s take a very simplistic example: I have a site with a button and a label and when I press the button, I want the label to say "Hello World". Rather than develop the button and label together I put them into their own widgets. When the button is pressed it tells the app site "HEY! I've been pressed". Then app site will then tell all the other components/widgets of the site "OK, if anybody is interested, that button over there was pressed" and hey presto the label now knows to change and say "Hello World".
That is a simplistic example but it’s the concept that is the most interesting and exciting part!
What could and will be better?
The XS Application Site concept is not without issues (hence my reference to still being developed). It still has some work to do on the placement of widgets (they can sometimes take on a will of their own during re-sizing) and also with the amount of data transferred to the client web browser during loading. Of course the big one is the theme of the SAPUI5 site itself (my personal bug-bear) but I am told that these issues and more are being worked on and will be released soon!
So now that we know what an app site is;
Let’s get started!
We are going to build a XS app site that has two widgets – a button and a label. That should illustrate how this concept works. I have posted the code I am writing here on github for anybody to download for more clarity.
Some pre-requisites
- SAP HANA System Rev 60+
- SAP HANA Studio Rev 60+
- The Delivery unit HANA_UI_INTEGRATION_SVC must have been imported and activated
- Your user must have the role “sap.hana.uis.db::SITE_DESIGNER”
- Any user viewing the site must have the role “sap.hana.uis.db.SITE_USER”
Ok so now I’m going to assume that you can create a new XS project with the correct setup with a “.xsapp” and “.xsaccess” file. If you need more info on those please check out thomas.jung course on openSAP which covers that topic in excellent detail.
The Button
So now our first task is to build our button. We are going to use a SAPUI5 button and for simplicity we are going to build it as a single HTML file with the JavaScript defined in-line.
So we start off with some basic HTML to get us started. This HTML will simply link to the SAPUI5 JavaScript libraries included with your SAP HANA installation and set us up to be able to develop our button.
Right, now that we have a good foundation, it is time to add the JavaScript that will setup our button. So as a starting point let’s get the button displaying and then hook it up to do something after:
Now when you save, activate and test your development you should see something simple like:
Right, so far we are dealing with completely standard SAPUI5 web development. Now we move to the fun part. We need our button to tell it’s containing App Site that it was pressed. We do this by publishing that event. Every event that is published has a key that identifies the event and a value indicating more information about that event. The method call could not be easier but best practice means we should be careful while publishing our events:
So in the above you can see that I access a variable provided to us by the App Site called “gadgets”. Within that variable I have access to another called “sapcontext” which is where we can access the “publish” method which takes two arguments; key and value.
You will also notice that in the above I have encased my “publish()” in a try/catch. The reason for that is twofold. Firstly I develop 90% of my code on my personal laptop, not a HANA system. Therefore if I am testing my code offline I like to gracefully handle the lack of these system specific pieces of functionality. Secondly I just don’t trust code I cannot see so therefore even if for some other reason this was not available, my code will work anyway! (call me paranoid!)
Right, so now that we have our button on screen, it is publishing our event and it is defensively coded we can move onto making a widget out of this HTML. First we need to create a descriptor file, which is basically an XML file in which we define the location of our HTML file as well as any SAP HANA specific features we intend to use.
An example of a XML file would be as below. The interesting part of this is the line where you can define the required features to be used in the widget. In this case we define that we want to use the “sap-context” feature which is what allows us to publish/subscribe to notifications.
We also list the full URL to our widget’s HTML file. Now that we have a descriptor we need to provide one final file to complete the widgetisation* of our button page. That file is a XSWidget file which defines the characteristics of our widget. At the moment these are defined using the creation wizard and do not contain much information however this may change in the future as the platform evolves. If you open the file after creation it will look something like this:
And with that we have create our first widget which contains a button which publishes a notification indicating when it is pressed.
The Label
Now we need a listening label to respond to this button push. So we start again with a HTML stub as we have above but this time we need to setup a label to be put into our HTML.
Note here that the ID of the div in my HTML in this case is called simpleLabel. Once that is in place we can test the page. All we should see is a label saying “”waiting”. Let’s not keep it waiting long so time to move onto the two last pieces of this puzzle. Telling the App Site we want to know when a notification has been posted by somebody and also what we want to do when we get a notification. Let’s start with the second one.
In the above screen shot we create a new function and assign it to an easily accessible variable. That function takes two arguments. The first is the topic, it is not something I will go into here but suffice to say it is not used at the moment and does not concern us. The context however does. That is where we get our notification data from.
- So first we retrieve any information about the notification we know the button has posted (that’s the notification with the key “EV_BUTTON_PRESSED”. This returns an array of notifications or just a single object if there was just one.
- Then we retrieve the latest version of that notification (there can be many so you may have to debug a bit here in the real world).
- Then if we have data from that retrieval we set the label text equal to that data.
- Finally we clean up by clearing up after our notification.
OK, now that we have defined what needs to happen when we get a notification we need to actually register to receive them.
The subscription is made up of two parts. First we call the subscription method within a standard function definition. This is to allow us to set that function to run when the widget is loaded rather than just when the page is loaded. The second section (in the try/catch) tells the widget settings (or HubSettings as it is called) to run our function when a connection occurs.
Now we have defined label widget we create a descriptor and xswidget file for them similar to what we did for the previous widget.
Putting it all together
Once they are activated it is time to create our actual XS App Site. So in our project create a new “Application Site”. Giving it a filename, title and description.
Once created the file should open and you will be prompted to login to the site designer (these will be your SAP HANA system credentials). If this is problematic please check your assigned roles to ensure you have the correct roles to be an App Site designer.
Once the designer is open you should see the standard UI5 template. On the right there are various options. One of these is a + where you can select widgets to drag into your site.
Once you have added your two widgets and positioned them correctly, save and activate your site.
Now, you would expect that at this stage you can go to the path to your project and point to the XS Appsite file to run the site however this is not the case. The XS Appsite runs as a query parameter to a standard SAP package. To find the correct URL for your package go to the cog icon on the top right of the XS App Site designer in which you will find a link to your site.
For convenience I usually add an index.html file to my project which does a redirect to your App Site’s URL however this is optional.
Once you launch your URL and login you should be presented with your full App Site with your widgets built in. You can hit your button to see your text change – all done through the context notifications.
So that’s it – you have now built and tested your first XS App site. The code for my examples can be found in my github repository - poc_hana_simpleXsAppSite (note the xsappsite file is not included).
Thanks for reading!
Brenton.
* Widgetisation is not a word but it makes sense here!
- SAP Managed Tags:
5 Comments
