A guide for setting up Titanium and beginning mobile development with ExCL
- WordPress
- Titanium
- Enhancing the ExCL App
- TiShadow
- Unit Testing and Continuous Integration
- Distribution For Testing
- Deploying to the App Store
- Known Issues
- Contributing
ExCL is a global initiative to change the way people learn. It seeks to empower museums to create their own mobile applications that they can use to inspire, educate, and connect with their visitors. Content is managed through a WordPress content management system by museum staff, and visitors will download the customized ExCL app, written using Appcelerator Titanium, to their mobile device. ExCL is also intended to be used by museums on kiosk devices and provides a kiosk mode for this purpose.
ExCL is divided into two parts: the content management system and the Appcelerator Titanium mobile application. This repository is for the Titanium mobile application. If you're interested in the content management side, click here to go to the Wordpress project.
This documentation is intended for ExCL developers and details the steps to setup and enhance the mobile application. We will describe the Titanium technical details, followed by tips on using a continuous integration build server and deploying to the app stores.
Titanium is a tool that allows developers to create applications for multiple platforms using a single project. For this project we are using Titanium in order to support both iOS and Android operating systems.
Appcelerator provides many useful features and examples, which can be found under the Titanium SDK Documentation
Titanium Studio is an Eclipse base IDE used for developing Titanium projects. Appcelerator allows developers to download Titanium Studio for free after setting up an account.
In order to view and edit the ExCL project using Titanium studio the project must be retrieved from github. We recommend that if you want to customize ExCL to your own museum extensively, that you consider forking the project and then cloning the fork. The master ExCL project contains generalized icons and will need to be customized before released as your own application.
If you are using a Mac or Linux computer, you go ahead and clone the repository. If you are using a windows machine, make sure you install git first. Here is a site that explains the process for Installing Git.
Open a command prompt, navigate to a desired folder run the following command:
$ git clone https://github.com/cmhouston/excl-mobile.git
A different tool for handling repositories and source control is SourceTree. Install SourceTree and clone the repository into your local file system.
After the project has been cloned to your local system execute the following steps to access it through your IDE
- Open Titanium Studio and go to File->Import
- Select Titanium->Existing Mobile Project and click next
- Browse your local file system and choose the folder you cloned from github
- Set your desired project name and click finish
The run option at the top left of the screen is by default unavailable. To enable this button execute the following steps:
- Right click on the project in your Project Explorer and open up the Properties
- Click on Project Natures
- Select Mobile and make it the Primary nature
- Click OK
After importing the project into Titanium Studio, open up the app/config.json file. You will need to put in the endpoint URLs that point to the ExCL Wordpress instance that you have already set up. The endpoints should look like http://myserver.com/wp-json/v01/excl/museum/25.
You get the ID number on the end of the URL from the ID of the museum in the Wordpress instance. This can be easily seen in the URL bar when editing the museum page in Wordpress.
Additionally, the app should be customized to fit your organization. Update the images in the app/assets folders and update tiapp.xml to reflect your own organization's information.
Titanium is designed to easily deploy and simulate projects for multiple platforms.
Titanium's built in android emulator is slow and has limited functionality. In order to avoid this issue the ExCL team chose to use the GenyMotion emulator. Appcelerator provides an article regarding Using GenyMotion with Titanium 3.2
There are a few more changes that need to be made in order to make GenyMotion compatible with a Mac. Follow these instructions for How to Set Up GenyMotion on a Mac
To deploy to an iOS device refer to Appcelerator's documentation on Deploying to iOS Devices
To deploy to an Android device refer to Appcelerator's documentation on Deploying to Android Devices.
If your computer does not recognize your Android device it is also possible to manually install the app.
- Enable Unknown Sources in the Device's settings app
- Connect the device to the computer via USB
- Build the Application by running it on an Android Emulator
- Navigate to (Project Folder)/build/android/bin on the computer and retrieve the APK file
- Copy this file to the Downloads folder on the device
- Disconnect your device and navigate to the APK file to install
When using the built in Emulators debugging is very simple. Refer to Appcelerator's documentation for Debugging on the Emulator or Simulator. When you debug an Alloy project like this one, put your breakpoints in the generated Resources folder's files for best success.
There are a few settings that need to be changed in order to debug on GenyMotion. If you are getting a "no SD card error" then follow these steps in order to resolve the issue:
- Go to C:\Users<username>\AppData\Roaming\Titanium\mobilesdk\win32\3.2.3.GA\android\cli\commands if on iOS, go to /Users/parivedadeveloper/Library/Application Support/Titanium/mobilesdk/osx/3.2.3.GA/android/cli/commands
- Edit "_build.js"
- Change line 1344 to
} else if (!emu.sdcard && (emu.type !== 'genymotion')) {
Now try debugging again and the error should be gone
- Adapted from http://stackoverflow.com/questions/21449970/titanium-studio-3-2-0-cannot-debug-using-genymotion-2-0-3e
Titanium uses an MVC Architecture. The Alloy framework holds these files within three separate folders: models, views, controllers.
ExCL uses an adapted version of the MVC architecture, where much of the logic is found within service files rather than within models. The service files can be can be found within the lib folder. A couple examples of services used are the dataRetriever and the sharingImageService.
Alloy allows developers to store global information. in ExCL all global variables are created and exported from Alloy.js.
Unit testing is another important part of ExCL, and the unit tests can be found in two places.
- Mocha unit tests can be found within the mochaTests folder, and can be run without compiling the application. (See Running The Unit Tests )
- Integration tests can be found withing the spec folder and can only be run on a compiled version of the Application. See Running The Unit Tests
For more in depth information, refer to Appcelerator's documentation on Alloy Framework
- All Window Navigation must be done using the Navigation Controller
- All fonts and colors are defined within the configuration file: config.json
Much of the ExCL code is split into various libraries which take control of specific functions of the app. The following libraries have corresponding documentation:
ExCL was created from a list of user stories involving enhancing the experience of a museum user. Many of these user stories have not yet been implemented. The user stories that we didn't get to are listed under the "Could Haves" sprint in our JIRA account. There are many other enhancements that are not new features, but instead changes to the current app. Below is a short description of each major area of suggested enhancements.
A complete list of user stories that we did not get to can be found in this Google Drive document. The user stories that we decided were possibilities for this summer (everything other than stories rated as "won't") are in JIRA, and the stories that haven't been completed yet can be found in the "Could Haves" sprint.
- Extend Tutorial to cover age filtering
- Screen timeout for kiosk mode that resets to the desired home screen
- Allow users to click on images to make them fullscreen, particularly the images on the component landing page and the post landing page
- Save name and e-mail on comment form to device so that users only enter it once
- Make the restart function smoother visually. This function is used for language switching, refreshing the in case of a lost network connection, and restarting the tutorial.
- Make all labels in the app fully customizable from Wordpress
- Allow users to e-mail content to themselves from kiosk mode
- Location tracking using low-energy Bluetooth beacons
- Bookmarking: Users can save suggested activities and view them later
- Allow users to activate built-in tool apps in their phone (stopwatch, calculator, etc.) from the app for relevant activities
- "You May Also Like...": Give users recommendations for other activities to try based on which activity they are currently viewing
- Questions and Results: Ask users questions about the activity they tried, and then display the results of this poll to the user
- Visitor-Generated Content: Allow users to provide content, such as activity recommendations for other users or questions for museum educators
- Allow visitors to earn badges
- Grade-specific recommendations for teachers
- Museum administrators can create surveys and polls to place in the app
- Upgrading Google Analytics to support custom dimensions for Screens
- Better error handling for network connection errors
- Refactor the Navigation Controller, as it is complicated and sometimes buggy
Please report all bugs to our JIRA account
For information on Ti Shadow, how to set it up, and how to use it, refer to the Ti Shadow documentation
We recommend using continuous integration to maintain the quality of the product. This repository has several unit tests written using Mocha and several integration tests using TiShadow's spec format.
Examples of ExCL's unit tests can be found within the project's spec folder
In this project, we are using Mocha for unit testing, Istanbul for code coverage and Sinon for mocking.
The root directory of the project contains a package.json file which will install all these tools, and run the unit tests as well.
- Open command prompt, and make sure you are in the root directory of the project folder. Type
npm installand hit enter. This will install all the tools and will create a folder callednode_modules. - To run the unit tests, you would run
npm testin the root directory. - To add more unit tests, place unit tests .js files under
app/spec/MochaTests. - Istanbul will provide metrics on the command line when you run
npm test - A
coveragefolder will be created by Istanbul in the root directory where you will be able to view a html version of the code coverage as well. The html file will be undercoverage/Icov-report, and once there you can openindex.html.
By default the coverage and node_modules folders won't be committed to the git repo when ever you commit something.
The code was designed to use continuous integration. We recommend using Buildbox to run a build agent on your local server. Buildbox integrates well with Github or Bitbucket, using hooks to allow Buildbox to automatically trigger builds on your local server. Follow Buildbox's getting started instructions and create two pipeline tasks to run (1) the unit tests and (2) the integration tests. In the "Script to Run" field, put scripts/unit.sh to run the unit tests and scripts/integration.sh to run the integration tests. The integration tests do require TI Shadow to be set up.
Occasionally you will need to change the permissions of the scripts/unit.sh and scripts/integration.sh scripts to make them executable. These can be found in the ~/.buildbox/{NAME_OF_BUILDBOX_AGENT}/excl-mobile/excl-mobile directory. You will need to chmod those to be executable if you have any problems.
For an app development project of any size, you will probably want to have a way to distribute alpha (pre release) versions of the app to testers and other interested parties (like your mom!). There are many cloud services out there that make it easy for even nontechnical people to install ad hoc builds of your app that you upload to the service. An added benefit is that it can be a convenient place to keep track of all your various builds, versions, sub-versions etc. Some of these services are free others are not. Some are iOS or Android only while others support both. Most have API's that allow you to programmatically upload your build right from your build script.
Some example services include:
Regardless of which service you use (if any at all), instructions for building for device deployment can be found here:
Both Google and Apple provide documentation about their app store requirements. These can be found at their developer sites:
- Images and videos included in a rich text field on the wordpress will not be cached on the device in or out of kiosk mode
We welcome contributions to this code. In order to contribute, please follow these steps:
- Fork this repository
- Make your changes
- Submit a pull request to have your changes merged in
- The pull request will be reviewed by our core team and possibly merged into the master branch