Tersus: Creating a native Android application

Creating a native Android applicationDate: Apr 27, 2015Tags:Android,Native vs. WebTersus Studio can generate native Android applications, integrating with the Android SDK to build an APK, test it using the SDK's virtual device, or install it on your own device.You will need to install the Android SDK on your development machine, by following these instructions - make a note of the SDK_HOME folder which you will need to provide later.If you are not running the latest version of Tersus (2.3.6), we suggest you upgrade, to ensure that you enjoy the newest features and bug-fixes. See the change log for more details of what's new or fixed. See Getting Updates for upgrade instructions.OverviewCreation of a native Android application can be divided into 2 main parts:

Application modelling

Building the native app

Developing your application

Model your application as usual. The only requirement is that your root system contains a <Mobile View>.

If you are starting a new application, it is recommended that you base it on one of the Mobile Application application templates (in File>New>Tersus Project) as a starting point, as they already contain the required view, and some additional mobile-related customizations.

In general, you cannot use services as-is in a native application, because your application has no server side component. If you do need to access server side functionality, you can do so using either of the following strategies:

Strategy 1 - Services modeled in the same application

You can include the services in the model as you would modelling a regular (web) application.

Testing while modelling (using the studio-embedded server and a browser) is no different, as the application is accessed as a web application.

Once the application is ready, deploy it to a server (see here).
You should now be able to access it as a regular web application deployed on the server - using a url in the format http://host[:port]/app/mobile.html - we suggest you do so to make sure it is deployed correctly, before continuing.

Before exporting the application to native, add the following javascript code to a .js file in the project's web folder:
```
if (tersus.isNative)
```
```
    tersus.serverURL='http://host[:port]/app';
```
Replace host, port (if required) and app with the values matching your deployment.

If the web folder and/or a .js file do not exist, create them - a suggested name for the file is server.js.

Note: You can test this procedure using the studio, rather than deploying your application to a standalone server, by doing the following:
- Use the studio machine's IP address (not localhost), as host in server.js.
- Launch the application from the studio's embedded server.
- Export the native application to your device.
- Connect your device to the same network as your studio machine.
- Launch the native application on the device.
- If you're getting Failed to execute service errors, which mean the application on the device cannot communicate with the server, recheck the above steps. To rule out network connectivity issues, try accessing the application as a web application from the device's web browser (using the url http://host[:port]/app) - if that fails you should check general connectivity settings on both the studio machine (server) and the mobile device (client).

Strategy 2 - Services modeled in a separate application

Model the required services as Callable Services in a separate application, and deploy it to a server.

To call a service from your native application, create a matching, empty service, with all required slots plus an additional <URL> trigger. The <URL> trigger should receive an appropriate URL pointing to the deployed callable service.

Native applications can access a local, client-side database on the device. Any database actions in your application, which are not modeled inside a server side process, will access the client-side database, with tables created as needed - see this page for more details.

By default, Tersus will create basic, text-based icons and (for iPhone) splash images for your native application. If you want to replace these basic images with your own design, create an images folder in your project's root folder, and place the images there. Note that if you do create your own images, they must conform to predefined specifications, such as, dimensions, background color, and other attributes that are mandated by the native platform sdks - check the respective platform documentation for further information.
File names and dimensions should be:

icon36.png (36x36 pixels) - Android ldpi icon
icon48.png (48x48 pixels) - Android mdpi icon
icon57.png (57x57 pixels) - iPhone low resolution / Android fallback icon
icon72.png (72x72 pixels) - iPad / Android hdpi icon
icon96.png (96x96 pixels) - Android default and xdpi icon
icon114.png (114x114 pixels) - iPhone high resolution icon
splash320x480.png - iPhone splash image (Default~iphone.png)
splash640x960.png - iPhone splash image (Default@2x~iphone.png)
splash640x1136.png - iPhone splash image (Default-568h@2x~iphone.png)
splash768x1024.png - iPhone splash image (Default-Portrait~ipad.png)
splash1536x2048.png - iPhone splash image (Default-Portrait@2x~ipad.png)
splash1024x768.png - iPhone splash image (Default-Landscape~ipad.png)
splash2048x1536.png - iPhone splash image (Default-Landscape@2x~ipad.png)

Note that splash images are used by the OS (iPhone-only at the moment) while loading the app, and before the Tersus client starts. Once the app has loaded, and the client starts executing it is replaced by a "Loading ..." message, until the <Mobile View> is rendered.
You can override this message by adding, to your project's web folder, a file called loading.txt, whose content will be displayed instead. Note that despite it's .txt extension, the file can contain HTML markup, which means you can display a splash image at this stage, using markup such as:

<div style="height:480px;background-image:url(images/splash.png);background-position:0px -20px;"></div>

Assuming you place the splash image file (called splash.png in this example) in the project's web/images subfolder.

Building the native app

Select File>Export>Native Mobile Application (or click the

toolbar button).

Set Target Platform to Android.
If this is the first time you're exporting to Android, you will be prompted to specify the location of the Android SDK folder (SDK_HOME). This location can be changed later via Window>Preferences>Tersus>Application Export Wizard.

Export Location is where the studio exports the android project to be compiled by the sdk, and where the sdk creates the final APK. This location should not include spaces.

Class Name and Package Name contain defaults which should be sufficient in most cases (certainly for testing), but can be changed as needed.

Select one of the Install on device options:

Install application in device: [Device ID] - Create a native application (debug package), install the application in the specified device, and launch it.
[Device ID] - is a preset, unique hexadecimal number embedded in your device by the device manufacturer.This option will only appear if a device has been connected via USB and is in debugging mode (i.e. the USB debugging option in Settings>Applications>Development is checked).
Install application in device: emulator-[serialNumber] - Create a native application (debug package), install the application in the specified emulator, and launch it.
[serialNumber] is determined by the Android SDK when launching an emulator, and appears in the emulator window's title.
This option will only appear if the matching emulator is already running.
Launch and install application in AVD: [AVD name] - Create a native application (debug package), launch the emulator [AVD name], install the application in the emulator, and launch it.
Create debug package - Create a native application (debug package) in the bin folder under the Export Location. It will not be installed in any emulator/device. You can install it manually (e.g. using the Android SDK) and perform your customized tests.
Create release package - Create a native application (release package) in the bin folder under the Export Location. You will be prompted to supply additional information (for instance, certificate details) in order to create a proper release package, which can then be uploaded to an app store (such as Google Play).
None (export only) - Create the project source, which can then be built into a native application using the Android SDK.

Click Finish to export.