Build a Native Module - Hello World

Overview

The icons or "modules" that a user sees in the home screen are either a completely native module (with no representation in the actual portal), a completely web-based module (showing the mobile web version of the portlet inside a WebView, like an iframe), or a native module that overrides a module from the portal (such as the Map and Directory modules in version 1.0. This is a quick example of how to build a native module with no dependencies on the portal.

Steps to Follow

1. Create Controller
2. Add to Facade and WindowManager
3. Add to Config and Set Icon

Create Controller

A controller in version 1.0 is only required to have three public members: key (unique string identifier for controller), open(), and close(). However, controllers typically need a few similar private properties and methods to function, such as app (the facade), init(), and common UI elements. For this example, we'll create a controller at Resources/js/controllers/HelloWorldController.js.

var HelloWorldController = function (facade) {
    var app = facade, _self = this, init,
    win, label, titleBar;

    init = function () {
        //Give it a unique key so the window manager and other members know what to call it
        _self.key = 'hello';
    };

    this.open = function () {
        win = Titanium.UI.createWindow({
            navBarHidden: true,
            backgroundColor: "#eee"
        });
        win.open();

        titleBar = app.UI.createTitleBar({
            homeButton: true
        });
        win.add(titleBar);

        label = Titanium.UI.createLabel({
            text: "Hello World"
        });

        win.add(label);
    };

    this.close = function () {
        win.close();
    };

    init();
};

• The constructor will only take one argument, like all other controller constructors, a reference to the Facade.
• In this controller, all we need to do in init() is set the unique key for the controller.
• In the open() method, we create a window to be opened using the Titanium API, create a titleBar to be placed in the window using the uMobile UI factory, and create a label to be added to the view using the titanium API.
• The close method is typically win.close() in all controllers, although it's safer to wrap it in a conditional to make sure 'win' is defined.

Add to Facade and Window Manager

We need to open Resources/app.js and add 3 lines of code to make sure the controller is fully registered. One line includes the new file from the file system, another line adds the controller to the facade, and another adds the controller to the window manager.

Somewhere around all of the other lines reading Titanium.include('...'); create a new line that reads:

Titanium.include('js/controllers/HelloWorldController.js');

(The order in which files are included isn't important here)

Next, around the lines that read app.registerController('', ...); add a new line that reads:

app.registerController('helloWorldController', new HelloWorldController(app));

This adds the controller to the facade, so the controller's public members can be accessed from other parts of the application if necessary.

Then we need to tell the WindowManager that this controller manages a window and can handle requests to open windows with the provided unique key. We pass the controller instance from the facade to the WindowManager, and it gets the data it needs automatically. The order in which this window is added in relationship to other windows isn't relevant.

windowManager.addWindow(app.controllers.helloWorldController);

And then we're done setting up the controller in app.js.

Add to Config and Set Icon

We need to declare the native module in the config (Resources/js/config.js), so that it will automatically get loaded when drawing the home window (portalWindowController). To do so, we find other native modules in the UPM.NATIVE_MODULES constant, and add another module object to the array before or after the other native modules.

UPM.LOCAL_MODULES.hello = {
    title: 'Hello World',
    fname: 'hello', //used when loading/sorting portlets in PortalProxy
    window: 'hello' //bound to icon when placed in portal window, tells window manager what to open
};

And then there's one more place we need to add the icon path, due to new functionality that was built in to display icons at different resolutions for different screens. Find the UPM.nativeIcons object, and add a new key/value pair for the new window:

UPM.nativeIcons = {
    ...
    hello: 'default-icon.png'
};

Open Titanium Developer (Assuming you've already configured your SDKs and successfully deployed the project previously), and click "Launch" in the emulator of your choice. You should see a new icon on the home screen for your window, and should be able to open the window with a simple titleBar and a text label on the screen.