Using a Module

Installing modules

Installing a module for a single project
Installing a module for all projects on a computer

Configuring your app to use a module

Updating tiapp.xml
Using require() to load the module in the app's code

Objective

In this section, you will learn how to install a module so that it is available to a single or multiple projects. Then you will see how to use a module within your project.

Installing modules

You can install modules in either of two ways:

So that the module is available to be used in a single project
So that the module is available to be used in all projects you develop on that computer

Once you have installed the module to your project or system, you then use it within your project with the same steps. We'll cover those after the installation steps.

Installing a module for a single project

To install a module for a single project:

Copy the module's zip file to the Resources directory of your Titanium project.
Build your project, at which point Titanium's python scripts will un-zip the module and copy the files to the appropriate directories within your project's directory hierarchy.

Alternatively, you could unzip the module's distribution file and copy the resulting directory tree to your Project root directory (the folder in which your app's tiapp.xml file is located).

Installing a module for all projects on a computer

To install a module so that it will be available to any project you create on your computer:

Copy the module to the root of your Titanium installation; see the table below for the location of this directory for your operating system and version.
Build your project, at which point Titanium's python scripts will un-zip the module and copy the files to the appropriate directories.

Operating System	Local Path
OSX (Pre-Lion)	`/Library/Application Support/Titanium`
OSX (Lion)	`~/Library/Application Support/Titanium`
Windows 7	`%ProgramData%\Titanium\mobilesdk\win32`
Windows XP	`C:\Documents and Settings\All Users\Application Data\Titanium`
Linux	`~/.titanium/mobilesdk/`

Configuring your app to use a module

Once you have installed the module to your project or system, you must configure your app to use it. This involves two steps:

Update the application's tiapp.xml file.
require() the module within your JavaScript code

Updating tiapp.xml

In the tiapp.xml file, inside the <ti:app> node, modify the <modules/> tag like this:

<!-- $MODULE_VERSION should be the same as "version" in the module manifest and directory number -->
<modules>
  <module version="$MODULE_VERSION">$MODULE_ID</module>
  <!-- For example, if we were adding the calc module: -->
  <module version="0.1">org.appcelerator.calc</module>
</modules>

Using require() to load the module in the app's code

Within your app's JavaScript files, you'll instantiate the module via the require() function:

var Module = require('$MODULE_ID');
// For example, to load the calc module:
var Calc = require('org.appcelerator.calc');

Finally, you'll use the module's object, properties, and methods to enable its features and functionality. Each module distributed in the Marketplace should include documentation and a sample app that demonstrates the basic use of the module. That information would be a great place to start with learning how to use a specific module.

Example Module Use

The following section illustrates how you would use one of the modules included in the Titanium Plus set. While the example cover an iOS use case, the same general steps apply to an Android module.

Download the module you want to use, for this example we will be downloading the AdMob module for iOS. The module can be downloaded here.
Install the module as described above.
In Studio, open the tiapp.xml file and switch to the XML view. Near the end of that file, you should find a line that looks like this:
```
<modules/>
```
Edit it to read:
```
<modules>
        <module version="1.0">ti.admob</module>
</modules>
```
(You might need to update the version number.)
The next step is the use of the module in your app, to do so we simply need to require (not Ti.include) the module with the following code:
```
var admob = require('ti.admob');
```

And finally it's time to use the module:

var adview = admob.createView({
    top:0,
    testing:true,
    adBackgroundColor:'black',
    primaryTextColor:'blue',
    secondaryTextColor:'green',
    publisherId:'<< your ID>>' // Replace this string with your own API key!
});
win.add(adview);

It might look like a lot of work at first, but once you get the hang of it its rather easy.

In this repo (in the admob directory) we have a sample app that makes use of the admob module for you to import into Titanium Studio and examine for your own use. While the code is all there, you will still need to install the module itself using the first set of instruction, but this will provide you with code that you know to be functional as long as the module is installed.

Summary

In this section, you learned that you can install a module for use by a single project or by all projects that you develop on a computer. Once installed, you have to modify your app's tiapp.xml file to support the module. Then, you must require the module into your app's code before you can implement its functionality.