Creating Custom Android Modules for the Titanium Mobile SDK: A Short-Term Solution

Introduction

A long-term strategy is being developed to provide developers using the Titanium Mobile SDK a way to include custom modules in their Android applications. In the meantime, this document can assist with a short-term solution for adding custom modules to for Android.

Whereas a long-term solution would most likely give the capability for developers to "drop in" a module (i.e., a JAR) into their Titanium project, in the short-term the only way to add a new module is to compile it side-by-side (so to speak) with core Titanium modules.

This document will therefore go through the process of creating a new module that "lives" inside of Titanium's core Eclipse project structure. This means that if you decide to proceed and create a new module using this procedure, you will either need to maintain your own fork of the Titanium Mobile SDK for your purposes, or -- when it is ready -- submit your module to become a part of Titanium's core repository. If you choose to contribute your module to the Titanium project, you will then need to sign the Appcelerator Contributors License Agreement.

So let's learn how to create a custom module that can be included in the Titanium Mobile SDK for Android.

Prepare Your Development Environment

1. First, you should fork the Titanium Mobile SDK repository and use git to pull it down to a working folder.
2. Make sure you have everything you need to be able to build the Titanium Mobile SDK on your development machine. You can find all the details in the build documents available in the "Installation and Building From Source" programming guides.
3. You will need Eclipse, as all existing Titanium modules are Eclipse projects, and these instructions will show you how to create a new module "side-by-side" with existing modules.
4. In Eclipse, use "File - Import - Existing Projects into Workspace" and choose the mobile sdk's android folder as the root, then import all projects thereunder.
5. To get the build working within Eclipse, you'll need to create classpath variable entries named ANDROID_PLATFORM (point to the/platforms/android-4 folder in your Android SDK folder) and GOOGLE_APIS (point to one of google_apis folders under the addons folder of your Android SDK).

Once you've proved to yourself that you can build existing Titanium projects inside Eclipse, you're ready to create a new project for your custom module.

Create a New Eclipse Project For Your Module

The easiest way to create a new project for your module is to make a copy of an existing module project and edit some folder names, file names and text file contents so that they reflect the directory, project and class names of your new module. That's what we're going to do in this example. We'll duplicate one of the smaller existing modules -- JSON -- and then rework some of its folders and files before importing it into Eclipse.

1. Duplicate the android/modules/json folder in the Titanium Mobile SDK sources. It's important that when you duplicate the folder, you do so in a way that will include hidden files (files with names that begin with a dot.) The OS X Finder's "Duplicate" option will do this correctly for you, if you are working on that platform. Just be sure that the files .gitignore, .project, and .classpath exist in the duplicate folder.
2. Rename the copy of the folder to a one-word name for your module. For this example, we'll pretend we're making a module to support the java.netsocket API, so we'll call the new folder socket.
3. Go into that new folder and make some deeper folder name changes and edit a few files:
   • In the root of your new project folder, use a programmer's text editor to edit the .project file and change the name of the project from titanium-json to titanium-[yourmod]. That would be titanim-socket for our working example.
   • Delete everything under the bin/ folder.
   • Under src/, change the deepest folder name to your one-word module name. That's socket in our working example.
   • Also change the existing .java file name from JSONModule.java to [Yourmodule]Module.java, so SocketModule.java in our working example.
   • Edit that .java source file to change the package ti.modules.titanium.json; line to package ti.modules.titanium.[yourmodule];, so package ti.modules.titanium.socket; in our working example.
   • Obviously you'll need to change the class name as well, but you can wait to do that in Eclipse.
4. Import the new project into Eclipse. Eclipse will register errors in the "Problems" view. One of those problems will be the fact that your module class name does not match its file name, so...
5. Edit your module class file and change the class name to [Yourmodule]Module so as to match its file name. In our example, that would beSocketModule. Also change its constructor to reflect the correct class name.
6. Remove the other methods from the class, as they apply to the JSONModule which you copied to use as a starting point for your own module.
7. At this point, when you save your class file, the Eclipse build errors (as shown in the Problems view) should go away. If they don't, you should try "cleaning" the loaded projects using the Project -> Clean... menu option inside Eclipse.

Add a Proxy Class for Your Module

In the previous section, you created your module class. That class is what will be referred to in Titanium Javascript code as Titanium.[Yourmodule]. In our example, our SocketModule class can be referred to as Titanium.Socket by developers using the Titanium Mobile SDK. Of course, it doesn't do anything yet, so we'll look at ways to add functionality in this section.

You will need one or more proxy classes to enable developers using the Titanium Mobile SDK to instantiate any type of functionality you plan to create in your module. Let's take an example from one of the core Titanium modules to describe what we mean by that.

You've probably seen and typed code similar to this while developing a Titanium app:

var win = Titanium.UI.createWindow( ... );

As you would guess from our explanation above concerning how your module class maps to a Titanium.[Yourmodule] module in Javascript,Titanium.UI comes from a class named UIModule in a package named ti.modules.titanium.ui.

.createWindow(...) then instantiates a WindowProxy class found in the same package as the UIModule. That's the way it is for all of theTitanium.XX.createYY() methods you frequently see in Titanium: XX maps to a class named XXModule in the packageti.modules.titanium.xx and YY instantiates a class named YYProxy in that same package.

So if you want developers to be able to instantiate a useful class from your module using Titanium.[Yourmodule].create[Yourclass], you need to create a proxy class named [Yourclass]Proxy.

For our example socket module, let's say we want to enable Titanium developers to instantiate a class representing a single client socket using syntax similar to this:

var socket = Titanium.Socket.createSocket({
    address: '127.0.0.1',
    port: 8073
});

You would then need to create a class named SocketProxy in your ti.modules.titanium.socket package.

Proxy classes need to extend TiProxy or one of its subclasses. For example, if your class will be some form of a view (similar to a View, TableView,ImageView, etc.), your proxy class would extend TiViewProxy.

Your best bet at this point is to study an existing core Titanium module that is most similar to the module you are thinking of creating, and see which proxy class is being extended, how the implementation of the functionality is achieved, etc.

The titanium-network project in Eclipse is a good starting point for reviewing existing Titanium modules for hints and ideas concerning your own implementation of a custom module. The fact that it is a relatively small project with a few classes makes it a good candidate for your review. We look at it in the next section concerning creating a class to manage a native object that provides your functionality.

http://developer.appcelerator.com/doc/mobile/android-custom-modules