Custom Widgets Android

The custom widget API is not final yet. It may change without prior notice!

A Tabris.js widget consists of a JavaScript API and a native client side implementation. This document describes how to create the native implementation for a custom widget on the Android platform.

In order to implement a custom widget you will need to build locally. Follow the Local Build guide.

Building upon Cordova infrastructure

To create a Tabris.js custom widget, we make use of the Cordova build system. Therefore we create a Cordova plugin that ties into Tabris.js specific APIs. In fact creating a Tabris.js custom widget does not require touching any of the Cordova specific Java APIs. All interaction with the JavaScript parts is enabled through Tabris.js specific APIs.

By leveraging the Cordova plugin architecture we are able to make use of the Cordova build chain and to provide a plugin.xml in our plugin to customize the build process. Once a plugin is defined it can be consumed by an app via the regular cordova plugin add <plugin-id/git-url> shell command or a <plugin /> entry in the config.xml of an app.

A working example of the concepts outlined in this document can be found here.

Receiving messages from JavaScript

Creating a custom widget requires handling incoming messages from JavaScript and sending messages back to JavaScript. The main entry point to this communication loop is the com.eclipsesource.tabris.android.TabrisOperator. The operator provides callback methods for all communication from JavaScript to the native client. The following snippet shows a basic operator:

The snippet above shows two important aspects of a TabrisOperator: The class has to have a two argument constructor CalendarOperator(<Activity>, <TabrisContext>) and the method getType() has to return the name of the custom widget as registered on the JavaScript side.

Registering an operator

To make an operator available to the Tabris.js Android runtime we have to register it. The simplest way is to declare our operator in a meta-data entry of the AndroidManifest.xml.

Since our custom widget is wrapped in a cordova plugin we can use the plugin’s plugin.xml file to add a new meta-data entry into the AndroidManifest.xml via the Cordova config-file directive. The following snippet shows how to declare our operator in the plugin.xml so that it is part of the final AndroidManifest.xml:

The snippet above inserts the meta-data element with its two attributes name and value into the AndroidManifest.xml. The name attribute has to be an application wide unique id with a prefix of com.eclipsesource.tabris.android.OPERATOR. In order to make the name unique we append the widget specific id .com.eclipsesource.tabris.calendar to the prefix. The value attribute of the meta-data element has to contain the fully qualified class name of our TabrisOperator implementation, eg.: com.eclipsesource.tabris.calendar.CalendarOperator.

Instantiating a widget

With the TabrisOperator registered we can now instantiate the Android View object that we want to display in the UI. To handle a create operation sent from JavaScript we implement the TabrisOperator.create(<Properties>) method in the operator:

The snippet instantiates the Android android.widget.CalendarView with the Activity passed into the constructor of the TabrisOperator. The properties argument could contain widget specific configuration directives but is not used in this example.

Handling properties

While we have instantiated our widget and passed it back to the system, it is not yet visible in the UI. To show an Android View it has to be added to the view hierarchy. In order to do that we have to process the parent property passed in from JavaScript. The parent provides the widget onto which we want to add our custom widget.

Since this is a very common scenario we don’t have to implement this ourselves but rather rely on the pre-existing com.eclipsesource.tabris.android.TabrisWidgetPropertyHandler. The TabrisWidgetPropertyHandler implements the TabrisPropertyHandler interface which provides get and set methods to support various properties.

By returning the default TabrisWidgetPropertyHandler we have covered all the common widget properties of Tabris.js but it is also possible to extend the TabrisPropertyHandler to provide your own implementation for a property or to add a custom property. The following snippet shows how to add support for the custom property date:

Destroying a widget

When a widget is no longer being used we also need to take care of destroying it. In case of our custom Android View we receive a destroy operation and are responsible for cleaning up any resource that are not required anymore and to remove the View from the view hierarchy: