Mobile App: Customization

From Complete Cyclos documentation wiki
Jump to: navigation, search

Basic customizations

  • Change the splashscreen:
    • Log in as admin and go to: Content Management > System Images.
    • Go to "Update system image" (on the bottom of this page) and upload the following Splashscreens:
      • Mobile: large splash image (must be 640px * 640px)
      • Mobile: medium splash image (must be 1024px * 1024px)
      • Mobile: small splash image (must be 1600px * 1600px)
  • Change the welcome text:
    • Log in as admin and go to: Translation > Application.
    • Search for the translation key "mobile.welcomeMessage" and give it the desired welcome text. Note: it could be that you write this message in English, but the user has set another language for the mobile app e.g. Spanish, this user will then see all buttons and texts in Spanish but only the welcome text in English.

Advanced customizations

Note: for small systems using Cyclos we strongly advice to use the App and not to create their own build. The maintenance cost will be quite high and also other costs have to be made such as getting the app in the appstores and paying for an apple developer account.

Environment setup

To be able to edit (create new functionality, change the layout etc.) the mobile app it is necessary to setup the development environment. It is easiest to first setup the complete development environment for Cyclos, please follow the steps Environment setup. Subsequently add the following project to the eclipse workspace "cyclos3_mobile" and "cyclos3_mobile_android" this can be done in exactly the same way as described in step IV of the environment setup.

Install GWT (Google Web Toolkit, only needed for more advanced customizations)

  • In Help > Install New Software, Select "Add..." (in the right top corner):
  • In Eclipse Window > Preferences > Google > Web Toolkit:
    • Ensure the default GWT SDK is set to last version (2.x). If nothing shows up in the list, click add, and then browse to the install directory of the SDK (under the plugin directory of eclipse,
  • When you have made more advanced changes make sure to GWT compile "cyclos3_mobile":
    • In project explorer, right click on "cyclos3_mobile" > Google > GWT Compile (by using add and remove you can decide if you want to compile the project for the web or for mobile devices).
  • It would be a good custom to first test the app in your browsers. Make sure "cyclos3_mobile" is compiled for the web. In the servers tab > Tomcat > modules (tab) > Add Web Module... > Add "cyclos3_mobile".

Download source code mobile app
The sourcecode can be downloaded from Source forge.


  • Requirements
    • Eclipse 3.4+

Eclipse Android installation

Phonegap can build the app online for all common smartphone platforms, but when changing the code of the app it is convenient to be able to directly test the app in a emulator. Below is described how to run the App in an Android emulator in Eclipse, please follow the steps below (for more information see [documentation for more information]):

After you've successfully downloaded the ADT as described above, the next step is to modify your ADT preferences in Eclipse to point to the Android SDK directory:

  • In Eclipse: select Window > Preferences... to open the Preferences panel (Mac OS X: Eclipse > Preferences).
  • Select Android from the left panel.
  • For the SDK Location in the main panel, click Browse... and locate your downloaded SDK directory.
  • Click Apply, then OK. If it asks you to install some missing components please see next which packages to install below.

In windows there will be a popup to install the following packages. Otherwise go to "In eclipse: Window -> Android SDK Manager" (if this gives problems when using windows you can also run it directly from the "SDK Manager.exe" right click on it and run as administrator):

  • Check the following packages:
    • Tools > Android SDK Tools
    • Tools > Android SDK Platform-tools
    • Android 3.0 > SDK Platform
    • Android 2.3.3 > SDK Platform
    • Android 2.1 > SDK Platform

Finally run the application in the emulator:

  • Go to Window -> AVD Manager, create some devices you wish to load in the emulator.
  • In the project explorer go to cyclos3_mobile > build.xml, right click on it > Run As > Ant Build... > Make sure "deploy-android" is checked and press "run".
  • In the project explorer go to cyclos3_mobile_android and right click on the project > Run As -> Android Application and select the created devices.
  • Now you should see the emulator running.

Common problems:

  • "The GWT SDK JAR gwt-servlet.jar is missing in the WEB-INF/lib directory"
    • In the problems tab, right click on this problem > quick fix > Select "Synchronize...." and press next.
  • "Android requires compiler compliance level 5.0 or 6.0. Found '1.7' instead"
    • In the project explorer, right click on "cyclos3_mobile_android" > Android Tools > Fix Project Properties.
  • Cyclos doesn't startup in the emulator correctly.
    • Quit Cyclos in the emulator by pressing "Esc", in the emulator go to: Settings > Applications > Manage applications > Cyclos > Uninstall.
    • Keep the emulator running and go to the project explorer again and go to cyclos3_mobile_android and right click on the project > Run As -> Android Application.
    • Now the application should run fine.


  • Requirements
    • Windows XP (32-bit) or Windows 7 (32-bit and 64-bit) or Mac OSX 10.6.4+
    • Java Development Kit (JDK)
    • Windows: Oracle JDK (32-Bit Version) or Mac OS X: Versions prior to Mac OS X 10.7 provided Java by default. OS X 10.7+ requires installation of Java.
    • Apache Ant
    • Windows: Apache Ant. or Mac OS X: Apache Ant is bundled with Java install.
  • Installation


  • Requirements
    • Xcode 4.3+
    • Xcode Command Line Tools
    • Intel-based computer with Mac OS X Lion or greater (10.7+)
    • Necessary for installing on device: Apple iOS device (iPhone, iPad, iPod Touch), iOS developer certificate
  • Installation

Common customizations

  • Disable host URL configuration

By default the application will ask user to enter the URL where Cyclos is running. To disable this feature and set a fixed URL you need to add the following line to properties.js file located under war/js folder

 hostUrl: "hereGoesYourUrl"
  • Change session timeout

By default the session timeout will expire after 5 minutes without any activity. To change this value you need to add the following line to properties.js file located under war/js folder and set the desired time in seconds

 sessionTimeout: 250 
  • Splash Screen

By default the application will display a splash screen if it is defined in Cyclos. This functionality can be enabled or disabled adding the following line to properties.js file located under war/js folder and setting the value to true (enables splash screen) or false (disables splash screen)

 splashScreen: false 
  • Change application name

The application name can be changed in config.xml file under war folder editing the following line


Note: To change the application name set in the specific Android Project (cyclos3_mobile_android) edit the following line in strings.xml file located under res/values

 <string name="app_name">HereGoesTheApplicationName</string>
  • Change application icon

The application icon can be changed in config.xml file under war folder editing the following lines

 <icon src="icon.png" gap:role="default" />	
 <icon src="images/57.png" gap:platform="ios" width="57" height="57" />
 <icon src="images/72.png" gap:platform="ios" width="72" height="72" />
 <icon src="images/114.png" gap:platform="ios" width="114" height="114" />	
 <icon src="images/32.png" gap:platform="android" gap:density="ldpi" />
 <icon src="images/48.png" gap:platform="android" gap:density="mdpi" />
 <icon src="images/72.png" gap:platform="android" gap:density="hdpi" />
 <icon src="images/96.png" gap:platform="android" gap:density="xdpi" />	
 <icon src="images/114.png" gap:platform="blackberry" />	
 <icon src="images/64.png" gap:platform="winphone" />	
 <icon src="images/64.png" gap:platform="webos" />

Because of the multiple platform deployment there are many sizes of the same icon, the icon name corresponds with the icon size.

Note: To change the application icon set in the specific Android Project (cyclos3_mobile_android) replace the ic_launcher.png icon under drawable-hdpi, drawable-ldpi, drawable-mdpi and drawable-xhdpi folders.

Operations (previous)