Skip to end of metadata
Go to start of metadata

Introduction

This guide walks through the steps to create, build and test an Windows module using Studio.  The equivalent CLI instructions are given in the information boxes near the top of each section.

Windows module prerequisites

To develop an Windows-based Module, you'll need all of the software required to build a Titanium application for Windows:

  • Titanium SDK
  • Supported versions of Visual Studio and the Windows Phone SDK, as described in Installing the Windows Phone SDK
  • Studio or the Appcelerator Command-Line Interface (CLI) for creating modules, and building and running test applications

Like Windows application development, Windows module development is only supported on Windows.

Create a new module

First, create a new module project.

CLI Instructions

Icon

 From a terminal, change the current working directory to your workspace and run:

In Studio:

  1. From the menu, select File > New > Mobile Module Project to open the New Mobile Module Project dialog.
  2. In the Project name field, enter test.
  3. In the Module Id field, enter com.example.test.
  4. In Deployment Targets, select Windows.
  5. Click Next, then click Finish.

Studio sets up a new folder called test that contains your module project.

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.

CLI Instructions

Icon

From a terminal, go to the module's windows directory and run the appc ti build -p windows --build-only:

After the build completes, unzip the built module in the Titanium SDK home path: (C:\ProgramData\Titanium).

In Studio:

  1. Select your module folder in the Project Explorer view.
  2. Verify Package and Windows Module are displayed in Launch Mode and Launch Target, respectively.
  3. Click the Package icon to open the Package Windows Module dialog.
  4. In Output Location, choose the Titanium SDK to install the module in the Titanium SDK home path to be accessed by any Titanium application.
  5. 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

CLI Instructions

Icon

From a new terminal window, change the current working directory to your workspace and run the following commands:

In Studio:

  1. From the menu, select File > New > Mobile App Project to open the New Mobile App Project dialog.
  2. On the Project Template page, select Default Alloy Project as the template type, then click Next.
  3. 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 Windows.
  4. 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.

CLI Instructions

Icon

Open the tiapp.xml and update the <modules/> element to include the module as a dependency to the project: 

In Studio:

  1. Open the tiapp.xml file located in the root directory of the project.

  2. Under the Modules section, click the Add button.

  3. Select com.example.test.
  4. Click OK.

Load the module and make module API calls

Icon

The module can be loaded by passing the module ID to the require() method, which returns a reference to the module that API calls can be made on.

Open the app/alloy.js file and replace the code with the following, which invokes API calls to the module:

app/alloy.js

Run the application

CLI Instructions

Icon

From a terminal that has the test app as its current working directory, run:

In the Studio toolbar, select Run in Launch Modes and select an Windows Phone simulator in Launch Targets.

Studio builds and launches the application on the select Windows Phone simulator.  Monitor the Console view for log output.

The console lines seen below show us that the module is working as expected.

Console

Modify the module

Let's modify the module code to create a view object and access a string property.

First, look at some of the default files created by the Titanium SDK.  Expand the windows folder.  Inside this folder are two files:

  • src/ComExampleTest.cpp: This is a boiler plate Module class. Every module requires a module class, which acts as the base API for the module.
  • include/ComExampleTest.hpp : This is a header file for the boiler plate class.

Add a property

A Module is a key/value store like an Object. Without any modification, you can set properties on a Module and then read them back at will as if they were properties. You can also override the getters and setters to add some custom logic. Modify the default module class files to store and retrieve a string value. First, modify the  ComExampleTestModule.hpp file to declare a variable to hold the string:

ComExampleTest.hpp

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.cpp file but not implemented. TitaniumKit provides useful macro to declare setter and getter, which is TITANIUM_PROPERTY_GETTER and  TITANIUM_PROPERTY_GETTER . TitaniumKit requires property value being treated as an JSValue datatype. Once you implement the method, register it using TITANIUM_ADD_FUNCTION in JSExportInitialize.

ComExampleTest.cpp

Add a function

In order to add JavaScript function to Module, modify the default module class files to return JavaScript value First, modify the  ComExampleTestModule.hpp file to declare a JavaScript function using TITANIUM_FUNCTION_DEF:

ComExampleTest.hpp

Next, modify the example function to actually return variable you just declared. These methods are already declared in the  ComExampleTestModule.cpp file but not implemented. TitaniumKit provides useful macro to declare JavaScript function, which is TITANIUM_FUNCTIONTITANIUM_FUNCTION should return JSValue datatype. Once you implement the method, register it using TITANIUM_ADD_PROPERTY in JSExportInitialize.

ComExampleTest.cpp

Firing callbacks

There are multiple way to fire JavaScript functions as a callback. First, the easiest way to fire callback is leveraging Titanium's event mechanics such as addEventListener.
So let say you are listening somethingfired event. In this case you can add listener in JavaScript like below.

app.js


In this case, you can fire this callback from the module by executing fireEvent like below.

ComExampleTest.cpp


There is another way to do the callback, by calling JSObject as a function directly. This is basic functionality on HAL framework.

app.js

 

Since HAL JSObject is callable, you can just execute it with arguments like below.

ComExampleTest.cpp

Next steps

  • No labels