- iOS module prerequisites
- Create a new module
- Validate the SDK version
- Build and package the module
- Test the module
- Modify the module
- Next steps
This guide walks through the steps to create, build and test an iOS module using Studio. The equivalent CLI instructions are given in the information boxes near the top of each section.
iOS module prerequisites
To develop an iOS-based Module, you'll need all of the software required to build a Titanium application for iOS:
- Titanium SDK
- Supported versions of Xcode and the iOS SDK, as described in Installing the iOS SDK
- Studio or the Appcelerator Command-Line Interface (CLI) for creating modules, and building and running test applications
ComExampleTestModuleIn addition, Python, Python setuptools and the Python markdown (or markdown2) module are both required by the module build scripts. For Mac OS X, Python and the Python setuptools should already be installed. For the markdown module, see Installing Required Python Packages.
Like iOS application development, iOS module development is only supported on OS X.
Create a new module
First, create a new module project.
- From the menu, select File > New > Mobile Module Project to open the New Mobile Module Project dialog.
- In the Project name field, enter test.
- In the Module Id field, enter com.example.test.
- In Deployment Targets, select iOS.
- Click Next, then click Finish.
Studio sets up a new folder called
test that contains your module project.
Validate the SDK version
You should validate the used Titanium SDK version inside the
titanium.xcconfig to point to a version that is installed on your machine. This is especially important to validate when using existing module projects that may have been created with a different SDK version.
Build and package the module
Next, build the module and package it. This process produces a ZIP file containing a binary library with unprocessed module assets, example code and documentation.
- Select your module folder in the Project Explorer view.
- Verify Package and iOS Module are displayed in Launch Mode and Launch Target, respectively.
- Click the Package icon to open the Package iOS Module dialog.
- In Output Location, choose the Titanium SDK to install the module in the Titanium SDK home path to be accessed by any Titanium application.
- Click Finish.
Studio builds and installs the module to the Titanium SDK home path.
Test the module
To test the module, create a test application and add the module as a dependency of the project. Then, load the module and make module API calls to the module reference.
Create a test application
- From the menu, select File > New > Mobile App Project to open the New Mobile App Project dialog.
- On the Project Template page, select Default Alloy Project as the template type, then click Next.
- On the Project Location page, enter the following information:
- In the Project Name field, enter Hello.
- In the App ID field, enter com.example.hello.
- In Deployment Targets, select iPhone and iPad.
- Click Finish to create the project.
Studio sets up a new folder called
Hello that contains the test application you will be using to test the module.
Add the module as a dependency to the project
To load the module in the application, you need to add it as a dependency to the project.
tiapp.xmlfile located in the root directory of the project.
Under the Modules section, click the Add button.
- Select com.example.test.
- Click OK.
Load the module and make module API calls
app/alloy.js file and replace the code with the following, which invokes API calls to the module:
Use require() to import your module
Before SDK 7.1.0, modules are imported as the following:
Since SDK 7.1.0, you can use import statements and template strings, see the following:
Run the application
In the Studio toolbar, select Run in Launch Modes and select an iOS simulator in Launch Targets.
Studio builds and launches the application on the select iOS simulator. Monitor the Console view for log output.
The console lines seen below show us that the module is working as expected.
Modify the module
Let's modify the module code to create a view object and access a string property.
Open the module in Xcode
Titanium creates a basic Xcode project, which is used to build the module. You can open this project in Xcode, the IDE used to develop iOS applications and used by the Titanium toolchain to build your iOS applications and modules.
- Right-click the
test.xcodeprojfolder and select Show In > Terminal.
In the Terminal, run the following command:
Your module project is now open in Xcode. Expand the
Classes folder and take a look at the default files created by the Titanium SDK:
ComExampleTestModule.m: These are the header and source file for the module class. Every module requires a module class (and only one module class), which acts as the base API for the module, such as providing the module ID, GUID, etc.
ComExampleTestModuleAssets.m: These are the header and source files to manage module assets. These files are auto-generated. You can ignore these for now in this tutorial.
Notice that all the files start with the module ID in camel case notation. Every file and class you add to the module project must start with name and every file and class you add must end with
Add a view proxy and view
To display any UI with a module, create a view proxy and view in pairs. Create the four files below for your Xcode project and save them in the module's
In Xcode, for each file:
- Right-click the project and select New File...
- For the header files, select Header File, and for the source files, select Objective-C File, then click Next.
- For the Objective-C files, enter the name of the file and click Next to proceed to the last dialog.
- For the header files, enter the name of the file in the Save As field.
- For both files, select the module's
- Ensure that the Target
- Click Create.
ComExampleTestViewProxy class extends the
ComExampleTestView class extends the
TiUIView class. The TiUIView can be added to other Titanium views and windows, which makes it the perfect place for a UIView to be added so that it can be displayed in a Titanium app. This class creates the native view to display. The class implements three methods of the
TiUIView class and a custom setter method:
initializeState: This method is called when the view is initialized. In this example, we are using this method as a place to create a native UIView which is called square.
rightproperties are invoked.
colorproperty is invoked, the method updates the background color of the square.
Notice that there is no code tying
ComExampleTestViewProxy. The naming convention is what causes the View to be connected to its ViewProxy.
() method. The name of the method is the name of the view class without the module ID, then prefixed with
create. For example, if the class was called
ComExampleTestMyView (rather than
ComExampleTestView), the method would be called
createMyView() (rather than
Below is an example of calling
createView(), and passing dimensions and color properties to the method.
Add a property
Modify the default module class files to store and retrieve a string value.
First, modify the
ComExampleTestModule.h file to declare a variable to hold the string:
Next, modify the example setter and getter to actually set and get the variable you just declared. These methods are already declared in the
ComExampleTestModule.m file but not implemented. Titanium requires that all setter methods be declared with the method name starting with
set and being passed an
foo string can be accessed using the
exampleProp property, and
Test the module
app/views/index.xml file and replace the code with the following, which loads the module and displays a red square:
app/controllers/index.js file and replace the code with the following, which invokes API calls to the module:
Build and install your module, then run the example app.
When the application starts running, you see should a red square in the middle of the screen and see the log output below, which means the application successfully loaded the module and called its APIs.
- For information about how to structure your module project, add assets or third-party frameworks to your module project or more details on how to use the CLI or Studio, see iOS Module Project.
- For information about how to construct the class components for your project, see iOS Module Quick Start.
- For more examples of using the module API, see the ti.moddevguide Github project.