Using jQuery plugins in Fiori apps (with SAPUI5)

[melanie_lauber]

Hi all,

A small blog this time to give you a short and simple guide on how to use jQuery plugins in your Fiori apps.

We all probably know that SAPUI5 comes with jQuery; we can use...
$.[JQUERY-METHOD]
...anywhere in our code.
And we can retrieve the jQuery object of our UI5 object with $(), for example: this.byId("someHtmlId").$()

But you all probably also know, that many smart heads out there create awesome jQuery plugins for us to reuse; the beauty of open source and shared culture 😄 !

But now you may wonder, how would you use the jQuery plugin in your Fiori app? Especially if it's an app, made for the Fiori Launchpad and not a freestlye app; so we don't have an index.html file. Well, this is what this blog will explain in very few (as you can see below) steps!

BIG EDIT 2020-03-16

Hi all. I am doing a huge edit with regard to a comment I got and the depreciated $.sap.require I had been using in my "old post". I will fully update all code to use non-depreciated method sap.ui.define. Apologies for the inconvenience but the good new is - it's even easier!

 

The Plugin

For this blog as an example, I'm using a plugin I truly love; the jQuery idle plugin. You can read more details about the plugin on it's github page as linked, but in short; you can react when the webapp goes idle (no mouse moving, no clicking, no nothing) and also when the webapp comes back to live. This can be very handy; for example you may want to auto-save data, if the app goes idle, to avoid losing the session and then lose unsaved data. That's just one example how this plugin can be used.

Download/clone the plugin

From the github page (as linked above), you can either clone the repository if you wish or just download the plugin (which is what I will explain below).

The plugin on the github page has several files for testing etc. However in this case we only need one file for the plugin to work (and that's not always the case! Some plugins require several files and I will add a code example, how to deal with those as well): jquery.idle.min.js (or jquery.idle.js if you prefer un-minified versions).

In Your Fiori App

In your app, decide where you want to use your plugin; On a certain view? On the whole app? Depending on your answer, I show you how to use the jQuery plugin:

1. Rename the plugin file(s) to not contain dots ("."), other than the file extension. So for example if you downloaded jquery.idle.min.js rename it to idleMin.js only (this is necessary due to plugin registering with "sap.require" - as far as I'm aware)


2. Create a new folder in your project, for example called jqPlugins for your jquery plugin(s) - this is up to you were you want to place the plugin, but keep in mind easy, intuitive readability


3. Upload the plugin file(s) into the created folder -> HOWEVER, IF the plugin requires several files I recommend creating a subfolder, for example jqPlugins/bigPluginName


4. Go to the controller of your view, where you want to use your plugin. Include the jquery plugin(s) in its sap.ui.define call at the very top of the file, for example:

// example plugin with just 1 file: idleMin.js

sap.ui.define([

	"./BaseController",

	"sap/ui/model/json/JSONModel",

	"../jqPlugins/idleMin"

], function (BaseController, JSONModel, jqueryIdle) {



// example bigger plugin, with several files (file1.js, file2.js), 

// including a stylesheet (plugin.css)

sap.ui.define([

	"./BaseController",

	"sap/ui/model/json/JSONModel",

	"../jqPlugins/bigPlugin/file1",

	"../jqPlugins/bigPlugin/file2",

	"sap/ui/dom/includeStylesheet"

], function (BaseController, JSONModel, bigPl1, bigPl2, includeStylesheet) {



// FOR STYLESHEETS:

// in  the controller's onInit method, add following per stylesheet file:

var sRootPath = sap.ui.require.toUrl("[NAMESPACE].[PROJECT-NAME]");

includeStylesheet(sRootPath + "/jqPlugins/bigPlugin/plugin.css");

 

Use the plugin

Now that it's registered, you can use the plugin according to its documentation. In the case of the idle plugin, here an example code you may want to try:

/**

 * Called when the view is finished rendering

 * @public

 */ 

onAfterRendering : function () {

	// use the jQuery idle plugin on the whole app

	this.byId("app").$().idle({

		onIdle: function(){

			console.log("now idle");

		},

		onActive: function() {

			console.log("active again");

		},

		idle: 10000

	});

}

What the above does:

1. I am getting the html div, which wraps around my whole app, through the id "app", and then I get the jQuery object of it, by simply calling $() -> this is is required, since it's a jQuery plugin, I need to work with the jQuery object!


2. Next, from the documentation I learned I can register the idle-listener by simply calling idle on the object and then react to onIdle (when the webapp goes into idle state) and onActive (when the webapp is active again). Lastly I can change the idle-timer property; above is only 10'000 milliseconds, meaning 10 seconds (which of course is very short, and only for fast testing purpose)

Start your app, open the debugging tools and console of your browser and then don't touch anything (not even the mouse). Watch the console and after approx. 10 seconds (after everything was loaded), you should see the text "now idle" appear. Move the mouse and you should immediately see "active again".

Conclusion

It is very easy to use jQuery plugins with Fiori apps; be smart, be innovative but don't reinvent the wheel; if there is a smart plugin already which does what you need, use it! We are in a shared innovation culture, in this intelligent age 🙂