Tersus: Creating a native iPhone application

Creating a native iPhone applicationDate: Apr 16, 2013Tags:iPhone,Native vs. Web Tersus Studio generates native iPhone applications in the form of Xcode projects that you can compile and sign using Apple's iPhone SDK.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 iPhone application can be divided into 2 main parts:

Application modelling and conversion to an Xcode project - This part is performed using the Tersus Studio on any platform.

Building the Xcode project into a native app - This part is performed using Apple's Xcode, and requires a Mac.

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.

To export your application:

Select File>Export>Native Mobile Application (or click the toolbar button).
Set Target Platform to iPhone.
By default the exported Xcode project will be created in the export/iphone subfolder of your application - you can set an alternative location via Export Location.
Click Finish to create the Xcode project.

Building the native app (requires a Mac)

Open the exported project using Xcode.

Test the project using Xcode's iPhone simulator.
Set the project target to Simulator and then Build and Run it.

To test it on a real device or upload it to the app store, you'll need to sign the code using certificates provided by Apple.
To do this you must first enroll in an Apple Developer Program, and then use the tools and follow the instructions provided by Apple to go through the required process.
We recommend you start with Apple's App Distribution Guide introduction (containing links to developer program enrollment), followed by the App Store Submission Tutorial.