Development - Titanium

From EPOD
Revision as of 17:54, 3 June 2013 by Anw (talk | contribs) (v0.1 - Initial draft - many sections as yet unwritten)

Android Development Guide

Development Environment Setup

Titanium

  • Download and install Titanium.

MAC

  • Once dpkg file is downloaded, run it, then drag titanium to applications.

WIN

  • Warning Warning:

GENERAL

  • Run the app.
  • Select the default workspace, always.
  • Login using supplied Titanium login details
  • Install 2.4 SDK through the Help/Install Titanium SDK/Install from Update stream/Release/2.1.4.GA
  • Suggested Titanium theme is Light, UI is Advanced.

SVN

  • Set up SVN as follows
  • First time you use the SVN repository (for example, when you import the project), you will be prompted to set it up and select a connector Choose the top one (SVN Kit 1.2.3)
  • Note: downloading: always accept the license agreement. Always restart when prompted.
  • Assumes you have access to the SVN repository on \\10.43.0.21\Projects\EPOD\_Development\SVN\epod

MAC

  • Set up a Server share to 10.43.0.21/Projects and enter the correct username and password.
  • Do this by choosing Add Server, entering smb://10.43.0.21/Projects
  • Then Import a project, and follow the wizard.
  • The SVN URL should be: file:///Volumes/Projects/EPOD/_Development/SVN/epod
  • Enter the username and password you want.

WIN

  • Warning Warning:

GENERAL

  • Choose to search for projects under this folder and import separately.
  • But realistically, you are only interested in ePODAndroid.
  • You can also install RapidSVN.

Titanium Module setup

two ways:

  • Use the Dashboard window to install
  • Click on My Modules
  • Click on install on:
    • barcode
    • paint
    • imageFactory

OR

MAC

  • Note: EXTRACT the zip files into the already-existent Modules directory, don't just leave the zips there. Watch out for Apple overwriting the entire folder rather than merging the two folders.

Android SDK

  • Download.

MAC

  • Install by extracting and copying the folders into the Applications folder.
  • Add to the PATH env variable:
  • from Terminal:
  • vi ~/.bash_login
  • Add:
    • export PATH=$PATH:/Applications/sdk/Platform-tools:/Applications/sdk/tools

WIN

  • Warning Warning:

Android Dev Setup

Run the ADK setup utility (called Android in Platform-tools) Download all info from 4.03 to 2.2, skipping all 3.X variants (no-one really needs Honeycomb).

XCODE v4.5

MAC ONLY

  • Download
  • Login to developer.apple.com with the supplied credentials.
  • Click iOS Dev Center
  • Click Looking for an older version of Xcode? Download Change search to Xcode 4.5 Click link to Xcode 4.5.1, around 1.5 Gb
  • Install
  • Double-click the downloaded file, then double-click the Xcode app inside.
  • Agree to everything.

Programming Guide

The entire program set is automatically documented from the source code. This is stored in 

P:\EPOD\_Development\Documentation\Android Client\index.html

Program Heirarchy

Under ePODAndroid:

  • CHANGELOG.txt - All versions and changes made for the application. Keep this file updated whilst changes are being made. A formal new version will be added when files are checked in. Check in all files with descriptive notations. tiapp.xml should be checked in with the fill comment from this file.
  • README.md - A descriptive header for the automatically produced source documentation.
  • tiapp.xml - the main controller of the Titanium project. Contains settings, version control, extensions and parameters.
  • i18n - multi-lingual files - see following section
  • platform - platform-specific files - see following section
  • Resources - the main coding area. Here are all the files that a developer would typically maintain or affect. See following sections.

i18n folder

Folders in here are organised per system language. Warning Warning:

platform folder

Warning Warning:

Resources folder

  • Android - Android-specific images
  • Database - The DAL (Data Access Layer). These are functions and objects that are used to directly affect or access data from the database. All objects are documented as part of the Namespace Database
    • DBConnection
    • PDA_CONTAINER
    • PDA_DEVICE_TYPE
    • PDA_JOB
    • PDA_JOB_GROUP
    • PDA_LOAD
    • PDA_PHOTO
    • PDA_PRODUCT
    • PDA_REASON_CODE
    • PDA_SERVICE
    • PDA_SERVICE_ACTIVITY
    • EPOD_SERVICE_PRODUCT_MASTER
    • PDA_SERVICE_ACTIVITY_MASTER
    • PDA_SERVICE_PRODUCT
    • PDA_SITE
    • PDA_USER
    • PDA_VEHICLE
    • PENDING_DATA
    • XF_AUDIT
  • images - Generic images
  • System - Reusable objects - documented as part of Namespace Systemm UI and Webservices.
  • ui - main screen objects - documented as part of Namespace UI.
  • app.js - This is the start point for the entire application.
  • Warning Warning: what calls what when
  • Warning Warning: Timed services
  • Warning Warning: Database - Version Numbering - how this works

Styling Objects

Warning Warning: Describe the problem and solution

  • Using style.js
  • How to add new styles and the issues doing so.
  • Care taken when specifying element, need to null them on orientation changes
  • Use of resMod/resModX
  • Standard controls with Create functions available that 'overload' the standard UI styles:
    • Label
    • Picker
    • Button
    • Table
    • Table Row
    • View
    • ScrollView
    • ImageView
    • Tab
    • Slider
    • Switch
    • TabGroup
    • Table View
    • Table View Row
    • Text Area
    • Text Field
    • win - Window
  • Standard Styles
    • Note Note: Most styles also have specific Landscape versions created (_land), which are use
    • small/smaller/medium/larger/large - font size helper classes
    • left/right - text/object horizontal alignment helper classes
    • generalButton - sets the display characteristics of a general button. Used in conjunction with positioning classes, as follows:
      • btnSplitBottom
      • btnSplitBottom_land
      • btnBottom
      • btnBottom_land
      • btnSplitMiddle
      • btnSplitMiddle_land
      • btnMiddle
      • btnTop
      • btnScan
      • btnLeft
      • btnCenter
      • btnRight
    • generalText/wideText - full-width positioning
    • halfText - half-screen width text box positioning (right-hand side)
    • generalLabel - general label styling
    • tableHead - header for a table or a title for a screen.
    • tableRow - general styling for a row, taking into account resolution modifiers for size.
    • evenRow - slight background styling for even rows.
    • tableView_Status/_A/E/I/X/C - used to format the row based on the status of the order, or change status after receipt. Used in Job List.
    • settingsRow - unused as yet.
    • portraitWindow/landscapeWindow/anyWindow - basic settings for any type of window. Always use anyWindow
    • instrLabel - class for instructions label on Job Details - should be an ID!
    • tabContainer/tabDetails/tabProducts/tabNotes/tabInfo/tabPreworkActivities/tabMCRefs - generic tab items
    • checkedBox/unCheckedBox - classes used by custom checkbox object.
    • tabOn/tabOff - classes used by custom Tab object
    • productTable - Warning Warning:
    • scanText/scanTextBtn - Warning Warning:
    • popupWinView - used for popup window views
    • scrollViewTable - used for mainly full-screen views that scroll vertically.
    • scrollViewRow - used for the above.
    • claused/cancelled/normal - used for Signature - container clausing.
  • Warning Warning: custom controls
    • Custom Tab
    • Checkbox
    • UDF - User-defined field object

ID naming conventions:

  • The window to which this element belongs, plus '_', plus the ID.

Example:

  • winMine_txtBlah

Iterating fields (for example in a table) would be ID'd with the iteration number:

  • winMine_lblBlah1
  • Warning Warning: Vehicle checks - configurable fields and how to use them.
  • Warning Warning: Scrolling views and why they're better and worse than a table.

Other

Warning Warning: entire section needs expanding.

  • Include files once - describe why
  • Describe synchronous and asynchronous parts of the code, and why return and callbacks are your friends.
  • When debugging on emulator and you want to pick up latest chjanges, you could click the run button again in Titanium. Faster can be clicking on the app within the emulator - it will reload almost every change (that has been saved). Sometimes it fails though.
  • above, when running again from titanium, get lots of errors regarding can't build because file is in use. You can try stopping previous background tasks, or you can persevere - usually picks up again after a few goes. Stopping and starting Titanium resolves lots of things...
  • Preference changes anf i89n (multilingual) changes do NOT get picked up when restarting the app from the emulator. In fact, sometimes you may need to force this by cleaning the project and rebuilding, then installing from Titanum again.
  • adb can timeout if left for a while. If you start the app on the emulator and it hangs, that's probably what happened. Start the app from Titanium. If that doesn't work, reset adb from DDMS. If that doesn't work, exit the emulator, the start the app from titanium - should load another emulator. If that doesn't work, restart your PC.
  • Warning Warning: add others here.

Notation

Follow standard notation as follows:

  • global - preceded with 'g'
  • variables preceded with 3-character type, for example:
    • str - String
    • obj - General or custom object
    • lng - Long
    • int - Integer
    • bln - Boolean/Flag
  • Titanium objects should be named as follows:
    • lbl - Label
    • pck - Picker
    • btn - Button
    • tbl - Table
    • tbr - Table Row
    • vw - View
    • chk - Checkbox
    • scr - ScrollView
    • img - ImageView
    • tab - Custom Tab or Tab
    • sli - Slider
    • swt - Switch
    • tgp - TabGroup
    • tvw - Table View
    • tvr - Table View Row
    • txt - Text Area or Text Field
    • udf - User-defined field object (also obj)
    • win - Window

Note Note: These lists are not comprehensive or infallible. They are intended to guide towards a maintainable, cohesive documentation. Examples:

  • global boolean to control Blah - g_blnBlahFlag
  • text field Blah - txtBlah
  • label for the text field above - lblBlah

Garbage Collection

Warning Warning: Although there are issues with garbage collection in Titanium, this information is still being verified. As standard, we should follow these procedures as they will make for easier garbage disposal, whatever the reason.

  • Create an object vars. Note Note: Although this doesn't obey the naming conventions above, it does allow for the easy conversion of existing code, and should be followed until all is complete. After, these conventions will change the name to objVars.
  • All variables should be created under this object in that form. For example, a Blah text field would be declared as
vars.txtBlah=Ti.App.style.creatTextField('winMine_txtBlah', ' ', {});
  • All events should be declared as a function variable, to easily identify them for event removal later. For example:
vars.AutoupdateEvent = function () {
  vars.winMine.close();
};
  • Upon closing the window:
    • remove any events attached to the window or the app referencing the window, referencing the function object used to create it.
    • Set the window object to null;
    • Set the vars object to null;
  • Close and null DB and RS objects after use, or you get runtime errors.

Source Control

When checking in items, use the Team Synchronisation view of Titanium so you can see all changes you have made from the baseline.

Click Synchronise when using for the first time - always synchronise changes before a build.

The legend on the filelist should indicate whether:

  • The local file is changed and needs committing.
  • The SVN file has changes in that you need to incorporate into your local files.
  • Conflicting changes (both of the above).

In all cases, this view can be used to see the changes and incorporate changes into your local file until the changes have been merged - simply double-click on the file to be shown a list of all changes. Use the buttons provided to search for, incorporate or ignore changes.

The following standard rules apply to Android work:

  • Assign the development to yourself (either through the standard Supimix procedures or from the Log List)
  • Check out the source code through the Source Control software or direct from the Studio software.
  • Make any changes and test locally.
  • When complete, check in your changes with an appropriate comment, initially referencing the log. For example:
    • 291925 - Fixed X when Y happens
  • Update the log to Development Complete status in Supimix (or Fixed status on a log list), ensuring that you enter resolution notes.
  • Assign the log to a tester, who will then test the functionality and close the log (or reassign to be released in a patch).

Commenting Code

Code is automatically documented through JSDoc, so valid commenting of code (functions, classes, properties, methods and files themselves) is important.

  • Comment with /** ... */ BEFORE the declaration of the item you wish to comment.
  • Multi-line comments should always be preceded with an asterisk on each line, as in the examples below.

Files should have a comment on the top as follows: 

/**
 * @file Description of the file
 * @namespace ANameForTheFile
 * @version 1.0
 */

Functions and definitions that are not part of a class should be commented as follows: 

/** 
 * This function does blah.
 * Links to external sites (like the documentation) can be done like this {@link http://172.198.45.54/calidus-assist/EPOD/index.php/PDA_Job_Details}. 
 * html can be inserted to make the comments look better in the generated documentation, as follows:
 * <ul>
 * <li>Address & Contact</li>
 * <li>Instructions</li>
 * </ul>
 * @param {function} funJDCallback Each parameter will be documented like this. Put square brackets around them to indicate optional.
 * @param {PDA_JOB} PDAJOB Links to other parts of the documentation can be made with the the link command, as follows: {@link Database.PDA_JOB} 
 * @returns {Ti.UI.window} The window object to be displayed.
 * @memberof ANameForThisFile
 */

Class definitions/prototypes should have the main function commented as follows: 

/**
 * This object is declared and instantiated in this file.
 * 
 * @memberof ANameForThisFile
 * @constructor
 **/

Class methods and properties should be commented as follows: 

/**
 * This method does as follows
 **/

Notes:

  • @memberof must reference an actual namespace that has already been declared, but not necessarily within this file. So, a namespace declared in file1 as UI can be referenced in file 2. Indeed, the file itself can be made a member of another namespace, to group lots of other namespaces together. So, for example, app.js is named UI, Login.js is named Login, but is a member of UI.
  • Properties and methods of a class do not need to be declared as a memberof something, as they are automatically part of the constructor class.
  • All other commented functions in Namespaced files must be a member of a namespace, or they will be listed as Global functions in the documentation.
  • Properties or methods of a class can be linked to with {@link namespace.class#property}
  • Functions or variables in a namespace must be linked as follows: {@link namespace.function}
  • @version should only be used on files. It should be version 0.1 while being written, then 1.0 when finished. The version only needs to be changed if there are major changes to the document.
  • For EPOD application specifics:
    • DAL objects should be a member of the Database namespace
    • New screens should be a member of the UI namespace
    • New connection-based files (i.e. webservices) should be a member of the Webservices namespace.

Testing

Emulator

Preparation and Installation

You need to download and install the Android SDK - latest here: http://dl.google.com/android/installer_r21.1-windows.exe. You should check the page at http://developer.android.com/sdk/index.html for the latest.

When installed, run SDK Manager, to download the different target platforms. Install the following as minimum:

  • Tools
    • Android SDK Tools
    • Android SDK Platform-tools
  • Android 2.3.3 (API 10)
    • SDK Platform
    • Google APIs
  • Extras
    • Google USB Driver

Note Note: You can optionally add in more modern Android versions if desired - the system works on everything up to and including API 16 (Android 4.1), but these take more memory and processing, so will run slower in the emulator, and will also affect the defaults when setting up a new emulator.

Set-up

Set up an emulator through AVD Manager, as below, using the New button:

  • Name: Demo
  • CPU/ABI: (ARM (armeabi)
  • Target: Android 2.3.3 (API level 10)
  • Skin: WVGA854
  • SD Card: 512M
  • Snapshot: true
  • hw.lcd.density: 240
  • hw.gps: yes
  • hw.keyboard: yes
  • vm.heapSize: 24
  • snapshot.present: true
  • hw.ramSize: 256

All the properties above the line are required when you choose to create a new emulator, those below the line are optional and are added using the Hardware Properties section in the New dialogue.

Note Note: The Ram could be made a little larger, (for example 512 Mb), but this configuration runs the system well.

Installing the App

  • Run the emulator.
  • Set the time (using the Menu button/Settings/Date and Time)
  • When started, install the apk through adb command line from the directory with the apk with:
    • C:\Users\yourusername\AppData\Local\Android\android-sdk\platform-tools\adb.exe install "CALIDUS ePOD.apk"
  • Note that this installation can take some time to complete.

Configuring the App

  • On start-up of the application, you will be requested to do some set-up. Choose Yes.
  • Enter the Site you have been provided.
  • Language does not currently change anything, although it will, and Chinese (as listed) is an option.
  • Style is your choice, Default is OBS standard, red is very different on the job list.
  • Enter the Webservice - usually one of:
    • http://www.calidus-web.com:9093/epod_dev
    • http://www.calidus-web.com:9093/epod_test
    • http://www.calidus-web.com:9091/epod_uat
    • http://www.calidus-web.com:9091/epod_trial
    • http://www.calidus-web.com:9091/epod_demo
  • It is advised to change Update Interval to 30 seconds.
  • Exit with the Back button on the emulator, or ESC.
  • Clear the popup with the Back button on the emulator, or ESC.

Using the Emulator

  • Selecting items can be done using the left mouse click.
  • Scrolling windows can be scrolled using dragging - left-click-hold on the window, move the mouse and then release the left mouse button.
  • Swiping on Tabbed windows can be achieved by dragging left or right on the window.
  • Text entry can be made through the pop-up keyboard on the device window or the emulator keypad.
  • With the emulator configured as above, the PC keyboard can also be used to enter data in text boxes. The numeric keypad will not work in Numlock mode.
  • ESC can be used as the Back key, to clear popup dialogues, move back one screen, clear drop-down lists, etc.
  • The Back, Menu, Search and Home buttons can be found on the soft keyboard in the emulator window.
  • You can change orientation using the numeric keypad (while NOT in numlock mode), using 7 and 9 to rotate the device).
  • You can navigate through options on the device with the cursor keys or the mouse wheel, if configured.
  • Notes:
    • The Tab key does NOT move the entry to the next text box - this is a Windows convention.
    • You can't copy from Windows and paste into the emulator.

Device

Installing the App

  • Install the application from the market

ORinstall through the SDK, which requeires following the set-up steps above, except for the following change:

  • Connect the device to the PC.
  • The device should automatically connect - if not, ensure you install any required USB device drivers. For example, for Samsung, you may need to install Samsung Kies - download from the internet.
  • When started, install the apk through adb command line from the directory with the apk with:
    • C:\Users\yourusername\AppData\Local\Android\android-sdk\platform-tools\adb.exe install "CALIDUS ePOD.apk"
  • Note that this installation can take some time to complete.

Configuring the App

  • On start-up of the application, you will be requested to do some set-up. Choose Yes.
  • Enter the Site of the installed user system.
  • Language does not currently change anything.
  • Style is the customer's choice, Default is OBS standard.
  • Enter the Webservice - this will be the URL of the installed user system. For test purposes, this is usually one of:
    • http://www.calidus-web.com:9093/epod_dev
    • http://www.calidus-web.com:9093/epod_test
    • http://www.calidus-web.com:9091/epod_uat
    • http://www.calidus-web.com:9091/epod_trial
    • http://www.calidus-web.com:9091/epod_demo
  • Additional settings regarding Vibration and Alerts can be set a required.
  • All other settings should default to reasonable values.
  • Exit with the Back button on the device.
  • Clear the pop-up with the Back button on the device.

Device Configuration

  • Ensure GPS is enabled for all location checks.
  • Ensure device registered to Google account, either for the specific customer account or a generic account for that customer generated and registered by OBS e.g. [email protected]
  • Ensure app is installed through the correct Google Play application link (currently this is the generic CALIDUS ePOD app, but there may be customer-specific app releases in the future i.e. CALIDUS ePOD for CustomerName).

Optional:

  • Ensure Wifi is enabled, but not linking to unknown sources.
Samsung Galaxy Note
  • Ensure that the time-out on the capacitive action buttons is set to the longest, or no time-out.
  • Ensure that the Camera is set to Lowest Resolution and Highest Compression/Lowest Quality.
    • Run the camera app.
    • Select the 'Settings button' bottom left hand corner.
    • Select Edit Shortcuts.
    • Add Image quality and Resolution to the top bar by dragging the icons.
    • Exit out of Shortcuts.
    • Click the Image Quality Icon and change to 'Normal'.
    • Click the resolution icon and change to '800x480'.

Application Use

Developer Debugging

Warning Warning:

  • Running it through the emulator
  • Debug mode and how it works
  • SQLite3
    • Root only
    • How it can be accessed
    • What you can do in it
  • DDMS and what it can do for you.

Release

Warning Warning: Whole section needs writing

Building

  • Description - keyfile, configurations, etc.
  • What process to follow:
  • Where to put the build files

Releasing

  • Document how the Google Play Developer website works
  • No passwords!
  • How to upload
  • When to change the description
  • Possible future use: different apk files per client possibly?

Then through market, or sideloading - show how sideloading can be enabled on a device.

Demo

As per testing setup.

Retrieved from "https://calidusassist.adcservices.apteancloud.com/calidus-assist/EPOD/index.php?title=Development_-_Titanium&oldid=675"