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
Building the App
You need various tools and source files including the following:
||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.
|| 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:
On OSX it may be of the form:
/Users/<username/Library/Application Support/Omnis Studio 5.X/
||In Eclipse select File ->Import, and in the Import window that appears, choose General -> Existing Projects into Workspace.|
|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.|
||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.
||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.
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
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.
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.
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:
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.
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.
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:
You should also set the standardmenu attribute to 0. This will prevent the development options menu from being opened.
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
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
In order to enable caching, locate the line “mWebView.clearCache(true);” in the OmnisAndroidClient.java source file, and comment it out (prefix it with “//”).
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:
- Follow a URL to the .apk file in the web browser.
- Email the .apk file to an email client on the device.
- Transfer the .apk to the device, then use a file manager application to open the .apk.
- Submit your app to the Android Market (requires sign-up, with a small one-off fee), or another, third party, App Store.
- ‘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.
Details on creating an iOS app can be found in TNJS0002.