Mobile App: Technical overview

From Complete Cyclos documentation wiki
Jump to: navigation, search

Architecture

Cyclos Mobile is a browser-based AJAX application. It has been developed using Google Web Toolkit (GWT) which allows us to write the application in JAVA and then compile the source to highly optimized JavaScript that runs across all browsers, including mobile browsers. For mobile deployment Phonegap is used which allows us to use a single codebase that targets iOS, Android, BlackBerry, and more, just using our web development skills instead of learning a new environment for every platform on the market. The application communicates with Cyclos using REST services, see REST services and Finding the REST services.

Phonegap

PhoneGap is an HTML5 app platform that allows us to author native applications with web technologies and get access to APIs and stores, it uses standards-based web technologies to bridge web applications and mobile devices and also is an open source implementation of open standards, that means developers and companies can use PhoneGap for mobile applications that are free, commercial, open source, or any combination of these.

This framework provides us three important things:

  • Build the application once with web-standards
  • Wrap the application in PhoneGap to access native APIs
  • Deploy the application to multiple platforms

See more at http://www.phonegap.com

GWT

Google Web Toolkit (GWT) is a development toolkit for building and optimizing complex browser-based applications. Its goal is to enable productive development of high-performance web applications without the developer having to be an expert in browser quirks, XMLHttpRequest, and JavaScript. GWT is used by many products at Google, including Google Wave and the new version of AdWords. It's open source, completely free, and used by thousands of developers around the world.

See more at http://developers.google.com/web-toolkit

REST services

The mobile App connects with Cyclos using REST services, the REST services are available on Cyclos 3.7 (and higher). The REST services do not require any web service client to be configured and should thus work instantly (you only have to enable the channel in the system settings and enable the channel for the group and the user and for the payment). The REST services use the same permissions as that member has in the Cyclos web application and therefor only needs the user identification and credentials. The REST services are completely described here: REST_Web_services.

Some REST services are public and do not require credentials, this can be used to check if the REST services are working, check the url: http://localhost:8080/cyclos/rest/general

  • Rest services does not handle session.
  • The session is alive in the mobile browser's memory and expires after 5 minutes (as default)
  • Session is destroyed when user log out the application or the application is ended/closed.
  • For the REST services the same rules apply as for the general web, when a user tries to login with the wrong username or credentials.

The mobile app needs to know where to find the REST services. Therefor the url of Cyclos needs to be set in the app, in this url it will look for the rest services or for a text file "cyclosMobileRedirect.txt". This text file can be used if the URL is to difficult or not nice enough for the user to remember see Login configuration page.

Miscellaneous

Configuration files

  • config.xml (Phonegap Build)

The config.xml file, as specified in the W3C widget specification, allows developers to easily specify metadata about the applications.

For more information check: https://build.phonegap.com/docs/config-xml


Handling different resolutions

The application has a layout completely fluid (it has no fixed widths) therefor it does not matter what size the browser window has, the content should always fit. The table below shows the common densities for smartphones:

Density name Full name Pixels Per Inch Comment
ldpi low-density ~120ppi
  • Low density Android.
mdpi medium-density ~160ppi
  • iPhone / iPod touch (Original – 3GS).
  • This is the baseline density for android.
hdpi high-density ~240ppi
  • High density Android.
xhdpi extra high-density ~320ppi
  • iPhone / iPod touch (4th Gen).
  • Extra high density Android.

See: http://en.wikipedia.org/wiki/List_of_displays_by_pixel_density and http://developer.android.com/guide/practices/screens_support.html


Style sheets

The application has three style sheets:

  • One for screens with low or medium pixel density screens (/cyclos3_mobile/war/css/mobile.css);
  • One for screens with high pixel density screens (/cyclos3_mobile/war/css/hdpi.css).
  • One for screens with extra high pixel density screens (/cyclos3_mobile/war/css/xhdpi.css).

The stylesheet mobile.css is always loaded and the styles from the hdpi.css overwrite some styles for higher pixel density screens. For example the font size and paddings will be bigger for high density screens. To determine high density screens CSS3 media queries are used, a media query consists of a media type and zero or more expressions that check for the conditions of particular media features. E.g: <link rel="stylesheet" href="css/hdpi.css" media="screen and (-webkit-device-pixel-ratio: 1.5)" />


Images

As a reference we take a pixel density of 160 ppi, on this density images of 16px * 16px have a nice real size. For low and medium density screens we will use the same images and css. For higher densities we will work with the following conversion table:

Name Density: 160ppi Density: 240ppi Density: 320ppi
Ratio 1 1.5 2
Icons sizes 16 24 32


The icons from the TopPanel and the MenuPanel are resized for different resolutions. A javascript determines (/cyclos3_mobile/war/js/library.js, function getDevicePixelRatio())the pixel density, depending on the pixel density the correct image is loaded:

  • screen < 200ppi, mdpi is used.
  • 200ppi <= screen < 300ppi, hdpi is used.
  • screen >= 300ppi, xhdpi is used.

Splashscreen sizes

To give systems using Cyclos the possibility to easily customize the look of the app, they can easily replace the Cyclos splash screen with a splash screen of their own. They only have to upload the new splashscreens as a system image in Cyclos, then the app will automatically download the new splashscreen and show it at the startup.

How to make the logo fit in the splashscreen.
Cyclos splashscreen as example.

There are three splashscreen images one for small resolution, one for medium resolution and finally one for high resolution screens. They have the following sizes:

Note 1: make sure the size of the files are not much larger then 90 kB, for old blackberry phones this can cause memory problems.

Note 2: the image is always exactly centered on the device. If the device is in landscape mode, the top and bottom will not be visible of the image. And when the device is in portrait mode the left and right part of the image will not be visible. See dashed lines in the picture on the left.

Phones do not only have other resolutions but also other aspect ratio's (ratio width height of the screen), here are some examples:

  • Samsung Galaxy S3 (1280×720) 16:9
  • IPhone 4S (960×640) 3:2
  • HTC ThunderBolt (800×480) 5:3


Besides the aspect ratio's also the phone can be turned, which also turns the aspect ratio around. To help systems to easily create a new splashscreen please see the image above (or download a transparent png here). Here all the possible aspect ratio's are shown with a dashed line in an image of 640 by 640 pixcels. Check out the other image above to see how the Cyclos splashscreen looks for the different aspect ratios. E.g. to see how the splashscreen looks on a Samsung Galaxy S3, hold vertically, follow the 9:16 lines. And to see how it looks horizontally follow the 16:9 lines.

Back button support

Back button can be used in Android devices, this button allows users to go back between the visited pages. When no more pages are available to go back the application will prompts the user to logout. When the user is the login page pressing the back button will close the application.

Session Timeout

The session starts when the user log in into the application. After 5 minutes (as default) without any activity, the session will expire redirecting the user to the Login page. The timeout also can be customized in properties.js file. The session needs to expire to make the system more secure.

Translations

Each label or text in the application can be translated. The application detects which language the browser of the mobile device is using, if a translation in this language exists, automatically this language will be used. The default language is English this language will be used if there is a problem detecting the language or if there is no translation for the specific language. The language can be changed trough the configuration menu.

GWT takes care of this translation, all translation files are stored in the folder: /cyclos3_mobile/src/nl/strohalm/cyclos/mobile/client/ e.g. /cyclos3_mobile/src/nl/strohalm/cyclos/mobile/client/Messages_de.properties. Currently the following translations exist, but more translations are included within every release:

  • Messages_de.properties
  • Messages_el.properties
  • Messages_en.properties
  • Messages_es.properties
  • Messages_fr.properties
  • Messages_it.properties
  • Messages_ja.properties
  • Messages_nl.properties
  • Messages_pt.properties
  • Messages_ru.properties
  • Messages_zh.properties

When adding a language make sure to store this in the file \cyclos3_mobile\src\nl\strohalm\cyclos\mobile\CyclosMobile.gwt.xml in both properties:

  • <extend-property name="locale" values="en,nl,es,pt,it,de,fr,ru,el,zh,ja"/>
  • <set-property name="locale" value="en,nl,es,pt,it,de,fr,ru,el,zh,ja"/>

Note: make sure not to add to many languages, gwt compiles a project for each separate language. If the size of the application with one language is 350 kB, then the size of the application with 11 languages is 11 * 350 kB.

  • In the translation it is not possible to use a single apostrophe ' if you want to display an apostrophe use two apostrophes and it will display as if it is one e.g. write I''m if you want to display I'm.
  • If you want to use special signs such as = ! # : please put a slash in front if this character e.g.: /! or /# and so on.

Version

As a general rule the marketplaces will handle the new versions. There is no build in functionality to ask people to update Cyclos. The name of the app will be Cyclos 3. The first version of the app is version 1.0 the next version will be 1.1.

Possible version conflicts and solutions:

  • New Cyclos version on server, old app version on mobile > Old app will always be compatible with all future Cyclos 3 versions, tests for the REST services are written so we always know when things break down and the app stops working.
  • Old Cyclos version on server, new app version on mobile phone > old functionality of the app will keep working, new functionality will show error, or will preferably be hidden by code in the app.


Introduction (previous) Interface and fields (next)