Omnis Technical Note TNJS0001Mar 2012

Building & Customizing the Android app

for Omnis Studio 5.2 only
for Omnis Studio 6.x see the 'Building & Customizing Standalone Apps' manual
by Jason Gissing

In addition to using the new JavaScript Client in the browser on any computer, tablet or mobile device, you can create standalone apps for iOS and Android based devices that have your JavaScript remote form embedded. To do this, there are two custom apps or "wrappers" for the JavaScript Client, one for iOS, the other for Android. The custom apps create a thin layer around a simple Web Viewer which can load your JavaScript remote form.

This document describes the steps required in order to create your own customized Android wrapper app for the JavaScript client. It should provide you with all of the information you need to create your own, branded Android app.

Building the App

You need various tools and source files including the following:

1)



 
Install Eclipse, the ADT plugin and the Android SDK. Follow the instructions here: http://developer.android.com/sdk/index.html
When you reach the point where the SDK manager prompts you to select SDK components to download, you should install the Android 2.1 SDK, as this is the version that the project targets. Later SDKs can be installed as well, should you wish, but are not necessary for this project.
2)





 
If you are using the 5.2 release of Omnis Studio, you should use this project. If you are using a later version of Studio; find the client/jsclient/wrappers/Android/OmnisJS_Android.zip file in your Omnis tree, and extract to a location of your choice. This is in the editable files section of your Omnis installation, so on Vista or later it will be of the form:
C:\Users\<username>\AppData\local\TigerLogic\OS5.x\

On OSX it may be of the form:
/Users/<username/Library/Application Support/Omnis Studio 5.X/
3)
 
In Eclipse select File ->Import, and in the Import window that appears, choose General -> Existing Projects into Workspace.

Localizable.strings file

4) In the following window, Select the Select archive file option, then use the browse button to find the Android wrapper app project archive. This is the client/jsclient/wrappers/Android/OmnisJS_Android.zip file in your Omnis tree (located as above).
5) Then click Finish, and the project should be imported into your workspace.
6)

 

 
When you first import the project, you may be met with some errors about being unable to resolve the target. This is because you may not have installed the same version of the Android SDK with which the project was created.
Right-click on the top level of the project and select Properties. In the window that opens, select the Android section, and choose a Project Build Target.

Localizable.strings file

7)

 
 
This should clear the errors. You may need to rebuild to completely clear them – from the Project menu, do a clean and then rebuild.
All being well this should build correctly, and you should not get any errors. If so, we are ready to start customizing the app.

Customizing the App

Renaming the project

Right-Click on the project in Eclipse (the folder at the top level of the Package Explorer) and select Refactor -> Rename. In the window which opens, enter the new name for your project, and uncheck the “Update References” box.

Localizable.strings file

To keep things simple, you are advised not to use spaces or special characters in your project name. Then click Ok.

Changing the Identifier

The first step of customizing your app is to change the Package Identifier. This is the unique ID for your app, and is what is used to identify it within the OS. As such you should use a reverse-domain-name style identifier to ensure you do not conflict with other apps.

Expand the src level of the project - at the top level of this is the package. Currently it is named com.tigerlogic.omnis.jsclient.android

Localizable.strings file

Right-click this package and select Refactor -> Rename.

Change the name to your own unique identifier, make sure that Update References is checked, then click OK.

Localizable.strings file

Next you need to update the Package Identifier in the manifest.

Open the AndroidManifest file in the top level of the project.

Under the Manifest tab of the opened window, the Package is defined at the top - click its browse button, select your package name, and then save the manifest file.

Localizable.strings file

While you are editing the manifest, you should also turn debugging off. To do this, open the Application tab, locate the Debbugable entry, and set it to False.

If you turn Debuggable off, the app is no longer signed with the built-in debug certificate, and you must sign the application yourself, using a valid certificate. Please follow Google's instructions for this at: http://developer.android.com/guide/publishing/app-signing.html

The OmnisAndroidClient.java source file may still be trying to import using the old package name.

Open OmnisAndroidClient.java and look for the line:

import com.tigerlogic.omnis.jsclient.android.R ;
Change this to:
import <your package name>.R ;

Or alternatively you can open this file, then push Ctrl-Shift-O. This will tell Eclipse to add/remove necessary imports automatically.

Open res/layout/main.xml, selecting the main.xml tab at the bottom of the opened window, so that you see the xml source.

This uses a custom layout class, which is still referenced by the old package name: (<com.tigerlogic.omnis.jsclient.OmnisAndroidLinearLayout)
Since you have changed the package name, you need to change this to refer to the OmnisAndroidLinearLayout class in your new package name. Change this in both the opening and closing element tags:

Localizable.strings file

Changing the app name

To change the app name, open the res/values/strings.xml file and change the value of app_name to your required name.

Localizable.strings file

Changing the app Icon

To change the app icon you should replace the icon.png files in res/drawable-hdpi/, res/drawable-mdpi & res/drawable-ldpi with your own icons of the same size. They should also be named icon.png. The different icons are for use by different devices, depending on their screen density.

Localizable.strings file

Defining the connection settings

The final stage to customizing your app is to set default connection settings so that it will connect to your web server on startup.

Open assets/config.xml, with the XML Editor:

Change the URL to point to the HTML page containing your Omnis JavaScript remote form on your server.

You should also set the standardmenu attribute to 0. This will prevent the development options menu from being opened.

Localizable.strings file

Set the other attributes as you see fit for your particular application. Details of these attributes can be found in the documentation.

Form & Script Caching

The app is initially set up to clear the cache each time it opens. This means that each time your application opens it will download your remote form and the JavaScript files every time. This was done to ensure that the remote form or JavaScript files are not cached on the client and therefore any changes made to these files are picked up by a client.

However, in a deployment scenario, you may prefer the startup speed benefits offered by caching the scripts. If you do take this approach, and you later update the scripts on your server, your clients will not receive the updated scripts automatically, but will continue to use their own cached versions. In this situation, you may like to provide an updated app to your clients, or ask them to manually clear the cache from within “Manage Applications”.
In order to enable caching, locate the line “mWebView.clearCache(true);” in the OmnisAndroidClient.java source file, and comment it out (prefix it with “//”).

Localizable.strings file

Installing to a device

Android is very liberal in the way it allows you to install apps onto your device. In general, as long as the device has a means of seeing the file, the OS will allow you to install it (assuming you have “Unknown Sources” enabled in the Applications Settings). When you Run your project on a connected Android device or emulator, an application file (.apk) is created in the bin folder of your project, in your workspace.

Using your custom Android App you can:

  1. Follow a URL to the .apk file in the web browser.
  2. Email the .apk file to an email client on the device.
  3. Transfer the .apk to the device, then use a file manager application to open the .apk.
  4. Submit your app to the Android Market (requires sign-up, with a small one-off fee), or another, third party, App Store.
  5. ‘Run’ your project from Eclipse on a connected and configured Android device.

Creating a Signed App

Before distributing your app, you must make sure to sign it with your own private key.
Google's description of this process can be found here. We recommend you read this first, especially the section describing the requirements of a private key. The ADT plugin has a wizard to do all of the legwork for you.

Right-click the root of your project in the Package Explorer, and select "Export".

In the Window that opens, select Android->Export Android Application.

This will open a wizard, which you should follow, creating your private key details using the guidance provided by Google in the above document.

When you are finished, a signed .apk file will be created in the directory you nominated. This app is now ready for distribution.

References

We have created an Android wrapper app for the Omnis JavaScript Quiz, as a proof of concept. This can be found on Google Play (Android marketplace). As such, your JavaScript app too has the potential to tap into these expanding markets.

Details on creating an iOS app can be found in TNJS0002.