Configuring and Customizing Your Appcelerator Titanium Project

Configuration

There are some necessary configuration edits that will need to be made to get uMobile working. These can all be found in config.js, which at the time of this writing is located in <project root>/Resources/js/config.js. The required configuration edits are:

• BASE_PORTAL_URL - String. The base URL to the server with uPortal (& other services). eg: 'https://umobile.unicon.net'
• PORTAL_CONTEXT - String. The path, appended to BASE_PORTAL_URL, to access uPortal. eg: '/uPortal'
• SERVER_SESSION_TIMEOUT - Integer. The time, in seconds, that a session will remain alive. eg: 2 * 60 * 60 //7200 seconds, or two hours
• LOGIN_METHOD - String (reference to static constant in LoginProxy). References the method used to log user's in to the application, such as CAS or LocalLogin. eg: LoginProxy.loginMethods.LOCAL_LOGIN
• ENCRYPTION_KEY - String. Used to encrypt/decrypt user's password stored in the local sqlite database. eg: 'um0b1le'
• FORGOT_PASSWORD_URL - String. Path to direct users to in a browser to recover their password. eg: this.BASE_PORTAL_URL + this.PORTAL_CONTEXT + '/p/forgot-password'
• MAP_SERVICE_URL - String. URL used to load map JSON data for the map module. eg: this.BASE_PORTAL_URL + '/MapPortlet/api/locations.json'
• DIRECTORY_SERVICE_URL - String. URL used to perform searches for users from the directory module. eg: this.BASE_PORTAL_URL + this.PORTAL_CONTEXT + '/api/people.json'

Optional parameters include:

• CAS_URL - String. URL to access cas login service. eg: this.BASE_PORTAL_URL + '/cas'
• LOCAL_MODULES - Array. Contains objects to be included in native app that either override existing portlets, or are only available in the native app. eg: this.LOCAL_MODULES.map = { title: 'map', iconUrl: 'icons/map.png', fname: 'map', window: 'map', doesRequireLayout: false }; doesRequireLayout indicates if it must exist in the JSON layout returned from the uPortal instance
• DEFAULT_MAP_REGION - Object. Tells the map the default area to pan/zoom to when loaded. eg: {{{ latitude: 34.052819, longitude: -118.256407, latitudeDelta: 0.005, longitudeDelta: 0.005 }}}
• nativeIcons - Array. Associative array indexed by fnames of modules, to override the icons returned from the portal with local icons optimized for device resolutions. eg: this.nativeIcons = {videos: 'icons/youtube.png'}
• directoryEmergencyContacts - Array. Contains objects containing emergency contact information to be displayed in home page of directory. eg: this.directoryEmergencyContacts = [{ displayName: "Westin Bonaventure Hotel and Suites",telephoneNumber: '(866) 716-8137',postalAddress: '404 South Figueroa Street$Los Angeles, CA 90071', url:'http://www.starwoodhotels.com/westin/search/hotel_detail.html?propertyID=1004'}
• phoneDirectoryNumber - String. If defined, will display in the directory default view, and allow users to call the school's phone directory from the app. eg: '888 555 5555'

Localization

There's a javascript file in the root called "localization.js", which contains an array called localDictionary, which is a collection of locales indexed by string (eg localDictionary['en_US']). Each locale is a dictionary object with a lower camel case english representation of each word/phrase (eg. getDirections: "Get Directions"). 

The locale string ("en_US") for the application is set in config.js, and can be retrieved anywhere in the application by calling Titanium.App.Properties.getString('locale'). However, for convenience, the dictionary is added to the facade which should be accessible by every controller in the application. The proper way to implement text anywhere throughout the application is to write app.localDictionary.translatedTextStringKey.

Updating Application Graphics

There are a handful of graphics that should always be customized when customizing uMobile for release, and some that are optional (such as icons and in-app graphics). At a bare minimum, you should update:

1. Application Icons (Icons plural because Android and iOS have different guidelines for icon creation. This doesn't include the icons inside the app.)
2. Application Splash Screens

Creating the Application Icon

Both Android and iOS have very specific guidelines on what an icon for your application should look like, as well as at what dimensions you should provide your icon. Appcelerator has some general information about creating application icons in their wiki, but the steps below go into a little more detail. 

http://wiki.appcelerator.org/display/guides/The+Application+Project+Structure#TheApplicationProjectStructure-Applicationicon

1. Apple's icon guidelines: http://developer.apple.com/library/prerelease/ios/#documentation/UserExperience/Conceptual/MobileHIG/IconsImages/IconsImages.html#//apple_ref/doc/uid/TP40006556-CH14-SW1
2. Android's icon Guidelines: http://developer.android.com/guide/practices/ui_guidelines/icon_design.html
   Since each OS has its own unique style of icon, a good approach is to create one icon for each, and save it at all the different required dimensions. 
   For iPhone and iPad:
3. Create an iOS icon at 512 x 512 (This size is used during the app submission process)
4. Save for iPhone at 2 sizes in the Resources/iphone folder, one for standard res (57 x 57) and one for Retina Display (114 x 114), such as ApplicationIcon.png & ApplicationIcon@2x.png. Titanium recognizes that adding @2x just before the file extension indicates that this asset is for retina display.
5. Save for iPad at 72 x 72 pixels, naming it ApplicationIcon_72.png
6. Create an Android icon using the guidelines in Android's UI Guidelines.
7. Save three resolutions of the icon in android/images/<high | medium | low>/ApplicationIcon.png. 72 x 72, 57 x 57, and 48 x 48. Note: The high, medium and low folders might not yet exist, so you need to create them.
8. In Titanium Developer, select the project on the left, select "Edit" in the top of the window, and set the "Application Icon" field to "ApplicationIcon.png".
9. When creating your iPad app, you might need to manually select the icon.
10. Test in the emulator to see if the icon shows up (you may need to delete the contents of the build/android folder, but not the folder itself. You may need to delete build/iphone, which is safe.)

Creating Splash Screens

Every platform utilizes a splash screen, an image that shows briefly while the application is loading. Since different devices have different display resolutions, the only attributes that should necessarily change with each splash screen are the dimensions. However, you can customize your splash screens as much as you'd like for different platforms and devices.

1. Create a standard portrait orientation splash screen in your graphic editor. It's probably easier to start with the biggest size, so if you're supporting iPad, you'll create a 768 x 1004 graphic (1004 instead of 1024 because of the status bar).
2. Save as <project-root>/Resources/iphone/Default-Portrait.png (This should always be the name of the file for iPad)
3. Rotate the image 90 degrees and change the size to 1024 x 748, re-arrange elements as necessary
4. Save as Resources/iphone/Default-Landscape.png (now both iPad splash screens are complete)
5. The process will need to be repeated for several more resolutions, listed below. 

   When saving your different resolutions of splash screens, you'll be overwriting default splash screens created by Titanium when you created your project. For Android, these defaults are located in Resources/android/images/ and in several folders named like "res-long-land-hdpi"

Matrix of Splash Screen Resolutions

Stylizing the Application

Styling in the application is managed through a javascript file in the Resources root of the project called "style.js". The "styles" object in the file is attached to the facade that's implemented and shared in every controller in the application, so it's easy to create and implement new styles as needed.

In titanium, when creating new "View" objects, or any UI object, a 'create' method accepts an object containing style attributes (and sometimes value attributes). The style.js creates the foundation for the object to be passed into the create method, which can be appended if additional values need to be passed in at creation time. For a reference of common properties of view objects, view the Titanium API documentation for Titanium.UI.View: http://developer.appcelerator.com/apidoc/mobile/latest/Titanium.UI.View-object

For example:

In style.js:

titleLabel: {
    color: '#000'
}

Implement the label without modifying any styles:

var titleLabel = Titanium.UI.createLabel(app.styles.titleLabel);

Or modify the label attributes before creating it:

var titleLabelOptions = app.styles.titleLabel;
var titleLabelOptions.text = "Title Text";
var titleLabel = Titanium.UI.createLabel(titleLabelOptions);