A guide for setting up Titanium and beginning mobile development with ExCL
- WordPress
- Adobe Air And FlashDevelop
- Enhancing the ExCL App
- 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 Adobe Air, 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 Adobe Air mobile application. This repository is for the Adobe Air 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 Adobe Air technical details, followed by tips on using a continuous integration build server and deploying to the app stores.
Adobe Air is a tool that allows developers to create applications for multiple platforms using a single project. For this project we are using Adobe Air in order to support both iOS and Android operating systems.
Adobe Air provides many useful features and examples, which can be found under the Adobe Air SDK Documentation
FlashDevelop is a free and open source (MIT license) source code editor. FlashDevelop allows developers to download FlashDevelop for free. No account setup is needed.
In order to view and edit the ExCL project using FlashDevelop 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-2.0.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 FlashDevelop 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
- Inside the folder select the More_App.as3proj file.
To run the app simply press F5.
After importing the project into FlashDevelop, open up the bin/config.xml 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 splash screens folders and update bin/config.xml to reflect your own organization's information.
FlashDevelop is designed to easily deploy and simulate projects for multiple platforms using Adobe Air.
To deploy to an Android device please see the AIR_iOS_readme.txt file in the root of the repository
To deploy to an Android device please see the AIR_Android_readme.txt file in the root of the repository
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 Adobe Air's documentation for Debugging on the Emulator or Simulator.
- To run the app for Testing and Debugging
- open bat/RunApp.bat and under :target you will be able to set your build out option (Android, iOS, or desktop.
- if building for desktop set the desired resolution under :desktop heading in bat/RunApp.bat
- Press F5 to build and run (if building for iOS or Android the app will be loaded on the corresponding connected device).
Under the Desk
ExCL makes use of an embedded SQL database. The database is used to save tutorial on/off settings as well as the settings for age filtering of posts. All of the functions related to saving/ retrieving data are found in DataManasger.as.
ExCL also uses the GoViral.ane extension by Milkman games but it is not neccessary for the app to function. In the case that the extension is not used the "sharing" tag in config.xml needs to be set to false. In addition the following lines must be commented out from application.xml found in the root of the repository.
<extensions>
<extensionID>com.milkmangames.extensions.GoViral</extensionID>
</extensions>
Adobe Air allows developers to store global information. in ExCL all global variables are created from GlobalVarContainer.as. Many of the Global Variables are set in config.php. GlobalVarContainer.as also parses the exhibit/ component/ post data.
- The majority of screens are handled by MainInterface.as.
- All fonts and colors are defined within the configuration file: config.xml
ExCL is now in version 2.0. It was created based on feedback and reccomendations of the v1.4 users. The app is programmed in such a way as to make better use of device screen surface area and to provide a smoother navigation than previous versions.
The following is a list of some of the improvements from v1.4 to v2.0
- Improved display of posts while age filtering is turned on.
- Better usage of screen space on most page layouts.
- Smoother navigation of exhibit's component slider on the Exhibits page.
- Cropped thumbnails and images throughout to allow for consistent layout
- Added a tutorial screen to Maps and Info pages in the case user views those pages prior to viewing the Exhibits page.
- Added Pinch-zoom tutorial to Maps page.
- Removed uneccessary display page under Info.
- Added additional loaders and smoother page transitions
- Fixed issue with some images and content not loading due to erroneous Word Press entries
- Fixed issue with the app crashing in Kiosk Mode
- Email and text sharing of posts working with optional GoViral plugin
- Database saves/ retrieves selected Age Filters
- Introduced multi-threading to cache loaded images
Please report all bugs to our CMH account
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 are not attached using the GoViral plugin for Android. Only text is currently shared.
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