Step-by-Step Guide to Creating Tabris.js Native Widgets on Android

Apache Cordova plug-ins are essential components in the app development that allow developers to use native device capabilities beyond the scope of the Tabris.js framework. Since Tabris.js uses a native UI and no HTML, most Cordova plug-ins will work with it, but not all. Plug-ins that manipulate the DOM will not work.

You can easily integrate these working plugins into your Tabris.js project. But what if you couldn’t find the one that fits your business requirements? Or what if you want to use native UI components that are not supported in Tabris.js?

In this case, you should create your own custom plugin. At first glance, it can be seen as a complicated job, but it is not difficult.

In this blog post, we are going to guide you step-by-step how to create a simple custom Cordova plugin that only works with Tabris.js. The new plugin allows users to create a Floating Action Button (FAB) on Android that represents the primary action in a Screen. We propose two ways in order to create basic scaffolding for the FAB plugin:

1. Clone this template project, then customize it for your own use cases. The template project allows you to start faster but you will have to go through a lot of renaming and adjustment operations. It is easy to miss something during customization that can even cause runtime errors.
2.  Use the Plugman tool to create a basic project structure, then create an inner empty Android project to be able to develop relevant native sources in modern IDEs. This approach is less error-prone in customization than the previous one but requires several steps in order to create the project.

We are going to navigate through all the steps in the second approach to explain the creation of the plugin project in more detail.

Create Plugin

Install Plugman:

Create plugin project:

It generates the following structure in the current directory:

Add Android platform:

Build package.json file:

Answer the options below:

We will end up with the following structure:

JavaScript Part

Now, we are going to implement platform-independent JavaScript part of the project.

To comply with plugin naming conventions, we have renamed the project from TabrisPluginFab to tabris-plugin-fab.

I suggest opening the project folder in modern JavaScript IDEs like Visual Studio Code.

Clean up plugin manifest file (plugin.xml):

Rename TabrisPluginFab.js file under www directory to FloatingActionButton.js.
Define custom floating action button widget as follows:

The new floating action button widget supports show and hide methods, image property, and select event.
Specify the new JavaScript file in plugin.xml:

The clobbers element is used to specify namespace under the window object, used to access the JavaScript API in our hosted Tabris.js project.

Native Android Part

We are almost done with the JavaScript API, and now it is time to create native implementation on the Android platform.

We can simply edit the TabrisPluginFab.java file under the src/android/ directory with text editors. But it is not practical these days, especially when dealing with compilation errors.

Let us create an empty Android project in order to manage native sources in modern IDEs like Android Studio, although it is not required by the consumer or the widget. First, create the project/android path in the root (tabris-plugin-fab) directory.

We assume that you have downloaded and installed the Android Studio.

Open the Android Studio and select the “+ Create New Project” in the “Welcome to Android Studio” window:

Select “No Activity” in the templates window.

Configure your project in the opened “New Project” dialog as follows:

Here is how it looks like in the “Project” window:

Now set the source directory of the new Android project to the tabris-plugin-fab/src/android by adding the following sourceSets block to the build.gradle in the app module level.

I suggest creating a new directory /com/tabris/js/android/fab in the source folder and the result will be:

Then move the TabrisPluginFab.java file to the new directory.
The project now looks like this:

Remove TabrisPluginFab.java and create a new FloatingActionButtonHandler.kt file instead.

We need Tabris Android library to reference Tabris.js specific native APIs. However, the library does not exist in central repositories. So we should first download the library from the Tabris.js website and then configure the Gradle to consume it from the local repository.

Download the latest Tabris Android library from the Cordova Platforms section (sign-in required), create the environment variable TABRIS_ANDROID_PLATFORM on your operating system, and point it to the downloaded library root directory.

Add the following maven block to the allprojects.repositories block in the build.gradle at the project level to consume Tabris Android library from the local repository.

Add Tabris Android dependency below to the build.gradle in the app module level.

We have completed the Android project configuration and are now ready to update relevant native sources.
Update the FloatingActionButtonHandler.kt file as follows:

Note:

The value of the type variable in the FloatingActionButtonHandler.kt should match the value of the _nativeType property in the FloatingActionButton.js file.

Add a new ImageProperty.kt file:

Finally, specify the following native code and modification to the AndroidManifest.xml file for the Android platform in plugin.xml.

FYI:

Do not forget to include other elements as needed, such as:

• <framework src="domain:dependency:version" /> when you use other Maven dependencies or bundled library projects.
• <resource-file src="..." target="..." /> when you use platform-specific resource files.
• etc.

Type Declaration

If you want to use the plugin with TypeScript (or those that want code completion in JavaScript projects), you should define types for your API by creating the following declaration file index.d.ts under the new types folder.

Testing Plugin

Now you can integrate the plugin into your Tabris.js project by adding the following tag to your Cordova configuration file (config.xml):

Or

When you build your app with the snippet below:

You will get the result below:

 

That is all. Hopefully, this blog post encourages more people to create their own Tabris.js plugins. If you have a question or recommendation, feel free to leave a comment below.

You can download the complete project from GitHub.