Build an Android App Widget for Tabris.js Apps

The app widget is one of the desirable features in mobile apps and highly requested by Tabris.js developers. Unfortunately, we cannot directly use Tabris.js to create home screen widgets. However, we can create it natively as a Tabris.js custom widget.

This article covers a complete tutorial on how to create a custom home screen widget plugin for the Android platform and how to use it in your Tabris.js project. We are going to create a plugin that renders a counter, increases or decreases it directly in the widget, and exchanges the value with a Tabris.js application. Additionally, we’ll create Tabris.js project example that renders received counter value and includes the TextInput that sends the input number to the home screen widget.

Building a custom home screen widget requires some experience in Tabris.js and Android development. We recommend reading the Tabris.js documentation about creating a custom widget in both JavaScript and Android parts.

So, here we go:

We start with a Cordova plugin project structure. I suggest using the project in this article as a template for your own app widget project.

In order to reference the Tabris.js specific APIs, download the latest Tabris.js Android Cordova platform, create the environment variable TABRIS_ANDROID_PLATFORM on your operating system, and point it to the downloaded platform root directory.

Open Android Studio and import project from the tabris-plugin-app-widget\project\android path.

We can automatically create widget provider class and relevant resource files with the help of Android Studio.

Right click on project-> New -> Widget -> App Widget.

Once you click on it, a frame will open. Provide a name for your widget (we named it a TabrisAppWidget).

Now Android Studio will create 3 files for you: TabrisAppWidget.kt, tabris_app_widget.xml, and tabris_app_widget_info.xml. You can also create these files manually as we did: TabrisAppWidgetProvider.kt, app_widget.xml, and app_widget_info.xml.

Update these classes and files respectively with the following codes:

Additionally, add the following new classes:

Receive data from Tabris.js application

Create TabrisAppWidgetHandler.kt class and CounterProperty.kt object.

Create TabrisAppWidget.js file under the tabris-plugin-app-widget\www path with the following code:

Provide details about the newly created module, sources, resources, and modifications on the AndroidManifest.xml file in the plugin.xml file.

Send data to Tabris.js application

We suggest using the tabris-plugin-launchmonitor in conjunction with the cordova-plugin-customurlscheme to be able to launch Tabris.js app by URL, and to read the launch parameters.

Add the following plugins to the your-tabris-js-project/cordova/config.xml file:

Calling the openApp  function in the AppWidgetUtil.kt class launches your Tabris.js app with the relevant counter parameter.

Use the JavaScript codes below for your example Tabris.js project:

That is all. Hope this blog post helped you understand how to implement the Android app widget properly in Tabris.js projects.

And you can download the complete project from GitHub.