Extending Titanium with native iOS and Android modules

Extending Titanium

Native iOS & Android
Modules

tiConf.eu, valencia, 24/02/2013

Olivier Morandi
Software engineer

http://titaniumninja.com
olivier.morandi@gmail.com
@olivier_morandi
https://github.com/omorandi

tiConf.eu, valencia, 24/02/2013 2

Module
development is so
2010

Why Bother?

• To leverage native features
★ Underlying OS
★ 3rd party libraries
• Performance
★ To optimize the User Experience


Learning Resources


Official Appcelerator Guides

• http://docs.appcelerator.com/titanium/latest/#!/guide/
Extending_Titanium_Mobile

iOS_Module_Development_Guide

Android_Module_Development_Guide


Source code

• Titanium Mobile SDK
★ https://github.com/appcelerator/
titanium_mobile
• Example modules from Appcelerator
★ https://github.com/appcelerator/
titanium_modules


Follow these guys
• Aaron K. Saunders: https://github.com/aaronksaunders

• Ben Bahrenburg: https://github.com/benbahrenburg

• Christian Sullivan: https://github.com/euforic

• David Bankier: https://github.com/dbankier

• Jordi Domenec: https://github.com/iamyellow

• Marcel Pociot: https://github.com/mpociot

• Matt Apperson: https://github.com/mattapperson

• Paul Mietz Egli: https://github.com/pegli

• Ruben Fonseca: https://github.com/rubenfonseca

• Russ Frank: https://github.com/russfrank


Inside Titanium
(A bit of architecture)


Titanium cli (node.js) + python scripts


Runtime (iOS)

JS APP

Parser

KROLL BRIDGE
JavaScriptCore
Bytecode Titanium
Modules
objective-c
gen
(API)
C++
Interpreter

IOS SDK


Runtime (iOS)

JS APP

Parser

KROLL BRIDGE
JavaScriptCore
Bytecode Titanium
Modules
objective-c
gen
(API)
C++
O JIT
N Interpreter

IOS SDK


Runtime (Android)

JS APP

V8
Parser

KROLL BRIDGE
Native Code Titanium
Modules
Java
gen
OPT
(API)
C++
Native Code

Android SDK


Terminology

var win1 = Titanium.UI.createWindow({
title:'Hello World',
backgroundColor:'white'
});

var label1 = Titanium.UI.createLabel({
color:'black',
textAlign:'center',
width: 100
});

label1.text = 'howdy?';
win1.add(label1);

win1.open();


Terminology
module
object
});

color:'black',
textAlign:'center',
width: 100
});

win1.add(label1);

win1.open();


Terminology
module
object
});

color:'black',
textAlign:'center',
width: 100
});

win1.add(label1);

win1.open();

he
cts of t
Obje A PI a
re
nium S
Tita in the J
cted pp
inje nt at a
ro nme
envi p
s tartu


Terminology
factory
method
});

color:'black',
textAlign:'center',
width: 100
});

win1.add(label1);

win1.open();


Terminology

title:'Hello World', creation
backgroundColor:'white' properties
});

color:'black',
textAlign:'center',
width: 100
});

win1.add(label1);

win1.open();


Terminology
proxy
object
});

color:'black',
textAlign:'center',
width: 100
});

win1.add(label1);

win1.open();


Terminology

});
view proxy
object color:'black',
textAlign:'center',
width: 100
});

win1.add(label1);

win1.open();


Terminology

});

color:'black',
textAlign:'center',
width: 100
});
proxy
property win1.add(label1);

win1.open();


Terminology

});

color:'black',
textAlign:'center',
width: 100
});

win1.add(label1);
proxy win1.open();
method


Proxies & Modules

Native View Type
Proxy iOS UIView
Android View

creates manages
extends extends

Module ViewProxy View

has a


Proxies & Modules
Interface
State:
properties
Actions:
methods
Events:
addEventListener(), fireEvent()

Native View Type
Proxy iOS UIView
Android View

creates manages
extends extends


has a


Proxies & Modules
Interface
State:
properties
Actions:
methods
Events:

Native View Type
Proxy iOS UIView
Android View

creates manages
extends extends


Methods for the integration within the
application lifecycle has a
•startup() (iOS)
•shutdown() (iOS)
•onAppCreate() (Android)


Proxies & Modules
Interface
State:
properties
Actions:
methods
Events:

Native View Type
Proxy iOS UIView
Android View

creates manages
extends extends

Additional members for the integration
Methods for the integration within the
application lifecycle
within the UI layout system:
•add()
has a
•startup() (iOS) •remove()
•shutdown() (iOS) •height
•onAppCreate() (Android) •width
•backgroundColor
•...


Let’s create a module


• Create
• Develop
• Build
• Deploy
• Debug


Module Development


iOS Prerequisites

• Same as for Ti app development on iOS:
★ Titanium SDK.
★ Xcode


Android Prerequisites
• Same as for Ti app development on Android:
★ Titanium SDK.
★ Android SDK (+ ANDROID_SDK environment variable)

• Additionally:
★ Android NDK (+ ANDROID_NDK environment variable)
★ Ant 1.7.1 (available in PATH)
★ gperf must be installed and in your system PATH.
★ [Eclipse]


Create (cli)
$ alias ti='~/Library/Application Support/Titanium/mobilesdk/osx/3.0.0.GA/
titanium.py'

OL
SCHO
OLD


Create (cli)
titanium.py'

$ ti create --type=module --id=ti.conf.sample --name=ticonfsample
--platform=iphone --dir=./ios

OL
SCHO
OLD


Create (cli)
titanium.py'

$ ti create --type=module --id=ti.conf.sample --name=ticonfsample
--platform=iphone --dir=./ios

$ ti create --type=module--id=ti.conf.sample --name=ticonfsample
--platform=android --dir=./android

OL
SCHO
OLD


Create (Ti Studio)


Module Boilerplate


Build & Install (cli)

$ ./build.py
$ unzip -uo ti.conf.sample-iphone-0.1.zip -d ~/Library/Application Support/
Titanium/


Build & Install (cli)

$ ./build.py
$ unzip -uo ti.conf.sample-iphone-0.1.zip -d ~/Library/Application Support/
Titanium/

$ ant
$ unzip -uo dist/ti.conf.sample-android-0.1.zip -d ~/Library/Application
Support/Titanium/


Build (Ti Studio)


Build & Install (Ti Studio)


Deploy
tiapp.xml
<?xml version="1.0" encoding="UTF-8"?>
<ti:app xmlns:ti="http://ti.appcelerator.org">
<id>com.omorandi.ticonftest</id>



<modules>
<module platform="iphone">ti.conf.sample</module>
<module platform="android">ti.conf.sample</module>
</modules>
</ti:app>

app.js
var ticonfsample = require('ti.conf.sample');

Ti.API.info(ticonfsample.example());

Ti.API.info("module exampleProp is => " + ticonfsample.exampleProp);
ticonfsample.exampleProp = "This is a test value";

Agenda
• Methods • Events
• Passing • Callbacks
arguments
• ViewProxies
• Returning values
• Exceptions
• Using properties
• Proxies

Proxy/Module Methods
return value
-(id)methodName:(id)args
{
NSString result = @"Hello World”;

//do something

return result;
}


return value
-(id)methodName:(id)args
{
NSString result = @"Hello World”;

//do something

return result;
}

no return value
-(void)methodName:(id)args
{
//do something
}


return value
return value no args
-(id)methodName:(id)args @Kroll.method
{ public String methodName()
NSString result = @"Hello World”; {
String result = "Hello world";
//do something
//do something
return result;
} return result;
}

no return value
{
//do something
}


return value
return value no args
-(id)methodName:(id)args @Kroll.method
{ public String methodName()
NSString result = @"Hello World”; {
String result = "Hello world";
//do something
//do something
return result;
} return result;
}

no return value no return value
@Kroll.method
public void methodName(String value)
{
{
//do something
//do something
}
}


Example: xml2json module
Expected API

var xml2json = require('ti.xml2json');

var json = xml2json.convert(xmlDoc);

https://github.com/omorandi/TiXml2Json


Implementation
@implementation TiXml2jsonModule

-(NSDictionary) convertXml:(NSString)xmlString
{
NSDictionary *jsObj;

//do conversion stuff

return jsObj;
}

-(id)convert:(id)args
{
ENSURE_SINGLE_ARG(args, NSString);

return [self convertXml:args];
}

@end


Implementation

{


return jsObj;
}

-(id)convert:(id)args NSArray of arguments
{
ENSURE_SINGLE_ARG(args, NSString);

}

@end


Implementation

{


return jsObj;
}

TiBase.h
-(id)convert:(id)args NSArray of arguments
#define ENSURE_SINGLE_ARG(x,t)
{ {
ENSURE_SINGLE_ARG(args, NSString); x = (t*)[x objectAtIndex:0];
}
}

@end


Utility Macros
TiBase.h
#define ENSURE_CLASS(x,t)
#define ENSURE_CLASS_OR_NIL(x,t)
#define ENSURE_TYPE(x,t)
#define ENSURE_TYPE_OR_NIL(x,t)
#define ENSURE_ARG_COUNT(x,c)
#define ENSURE_SINGLE_ARG(x,t)
#define ENSURE_SINGLE_ARG_OR_NIL(x,t)
#define ENSURE_DICT(x)
#define ENSURE_ARRAY(x)
#define ENSURE_STRING(x)
#define THROW_INVALID_ARG(m)

...


Types

Supported Directly Conversion Utilities
NSString
NSDictionary #import "TiUtils.h"

NSArray CGFloat f = [TiUtils floatValue:arg];
NSInteger f = [TiUtils intValue:arg];
NSNumber NSString *value = [TiUtils stringValue:arg];
NSDate TiColor *bgcolor = [TiUtils colorValue:arg];
NSNull UIColor *backgroundColor = [bgcolor color];

TiProxy


Return Values
• Single Value (NSString, NSNumber, …)
• Collections (NSArray)
★ Converted into a JS Array object
• Dictionary (NSDictionary)
★ Converted into a JS object
★ key->value ===> property->value
• Proxy (TiProxy)

Return Values
• Single Value (NSString, NSNumber, …)
• Collections (NSArray)
• Dictionary (NSDictionary)
★ Converted into a JS object TS
BJEC
★ key->value ===> property->value DO
SE
EA
EL
OR
• Proxy (TiProxy) UR
NA
UT

RET

xml2json Android
import org.appcelerator.kroll.KrollDict;

@Kroll.module(name="Tixml2json", id="ti.xml2json")
public class Tixml2jsonModule extends KrollModule
{

@Kroll.method
public KrollDict convert(String xml)
{
KrollDict json = null;


return json;
}

}


xml2json Android
import org.appcelerator.kroll.KrollDict;

@Kroll.module(name="Tixml2json", id="ti.xml2json")
public class Tixml2jsonModule extends KrollModule
{
KrollDict.java
@Kroll.method public class KrollDict
extends HashMap<String, Object>
public KrollDict convert(String xml)
{


return json;
}

}


Types

Supported Directly Conversion Utilities
String
int import org.appcelerator.titanium.util.TiConvert;

float int val = TiConvert.toInt(obj);
double float val = TiConvert.toFloat(obj);
boolean double val = TiConvert.toDouble(obj);
boolean val = TiConvert.toBoolean(obj);
Object[] int color = TiConvert.toColor(str);
HashMap<String, Object> ...
TiProxy

http://builds.appcelerator.com.s3.amazonaws.com/module-apidoc/2.0.0/android/org/appcelerator/titanium/util/TiConvert.html


Return Values
• Single Value (String, Integer, …)
• Collections (Object[])
• Dictionary (HashMap<String, Object>)
★ Converted into a JS object
★ key->value ===> property->value
• Proxy (TiProxy)

Polymorphic Methods
-(id)convert:(id)args
{
ENSURE_ARG_COUNT(args, 1);

id arg = [args objectAtIndex:0];

if ([arg isKindOfClass:[NSString class]]) {
return [self convertFromString:arg];
}
else if ([arg isKindOfClass:[TiBlob class]]) {
return [self convertFromData:arg];
}
else {
[self throwException:@"Expected blob or string argument"
subreason:nil location:CODELOCATION];
}
}


Polymorphic Methods

public KrollDict convertFromString(String xml);
public KrollDict convertFromBlob(TiBlob blob)

@Kroll.method
public String convert(Object arg) {
if (arg instanceof String) {
return "string";
}
if (arg instanceof TiBlob) {
return "blob";
}
throw new IllegalArgumentException("Invalid argument type,
expected blob or string");
}


Varargs

-(void) varArgsMethod:(id)args
{

for (int i = 0; i < [args count]; i++) {
id arg = [args objectAtIndex:i];
// do something with arg
}
}


Varargs

@Kroll.method
public void varArgsMethod(Object[] args) {
for (int i = 0; i < args.length; i++) {
Object arg = args[i];
// do something with arg
}
}


Properties

set module.propertyName = "HELLO";

get Ti.API.info("Property: " + module.propertyName);


Properties
TiMyModule.h

@interface TiMyModule: TiModule

@property (nonatomic, readwrite, retain) NSString* propertyName;

@end

TiMyModule.m
@implementation TiMyModule: TiModule

@synthesize propertyName;

@end


Properties: Setter/Getter

- (void) setPropertyName:(id)args {
// set property and do stuff
}

- (id) propertyName {
// do something and
return value;
}


Properties: Setter/Getter
@Kroll.module(name="My", id="ti.my")
public class MyModule extends KrollModule
{
private String propertyName;

@Kroll.getProperty @Kroll.method
public String getPropertyName() {
return propertyName;
}

@Kroll.setProperty @Kroll.method
public void setPropertyName(String value) {

propertyName = value;
}
}


Constants
var smsModule = require('ti.ios.sms');

function sendCallback(e){
switch (e.result) {
case sms.SENT:
result = 'SENT';
break;
case sms.FAILED:
result = 'FAILED';
break;
case sms.CANCELLED:
result = 'CANCELLED';
break;
}
Ti.API.info("Property: " + module.propertyName);
}


Constants
https://github.com/omorandi/TiSMSDialog/blob/master/Classes/ComOmorandiSMSDialogProxy.m

//create the accessor methods for the SENT, CANCELLED and FAILED
constants
MAKE_SYSTEM_PROP(SENT,MessageComposeResultSent);
MAKE_SYSTEM_PROP(CANCELLED,MessageComposeResultCancelled);
MAKE_SYSTEM_PROP(FAILED,MessageComposeResultFailed);


Constants

constants
TiBase.h
#define MAKE_SYSTEM_PROP(name,map)
-(NSNumber*)name
{
return [NSNumber numberWithInt:map];
}


Constants

constants
TiBase.h
#define MAKE_SYSTEM_PROP(name,map)
-(NSNumber*)name
{
return [NSNumber numberWithInt:map];
}

@Kroll.module(name="Sms", id="ti.android.sms")
public class SmsModule extends KrollModule
{
@Kroll.constant
public static final int SENT = 0;
@Kroll.constant
public static final int CANCELLED = -1;
@Kroll.constant
public static final int FAILED = -2;
}


Proxy Objects

var smsModule = require('ti.ios.sms');

//create the smsDialog object
var smsDialog = smsModule.createSMSDialog({
recipients: ['+123456789'],
messageBody: 'hello'
});

smsDialog.open();


Creating a Proxy
TiIosSmsSMSDialogProxy.h
@interface TiIosSmsSMSDialogProxy: TiProxy<MFMessageComposeViewControllerDelegate>

@end

TiIosSmsSMSDialogProxy.m
@implementation TiIosSmsSMSDialogProxy

- (void)open:(id)args
{

// retrieve properties (either set on creation, or later)

NSArray * recipients = [self valueForUndefinedKey:@"recipients"];
NSString * messageBody= [TiUtils stringValue:[self valueForUndefinedKey:@"messageBody"]];

// do stuff

}

@end


Proxy Objects

var smsModule = require('ti.android.sms');

//create the sms object
var sms = smsModule.createSms({
recipient: '+123456789',
messageBody: 'hello'
});

sms.send();


Creating a Proxy
@Kroll.proxy(creatableInModule=SmsModule.class)
public class SmsProxy extends KrollProxy
{
private String messageBody = null;
private String recipient = null;

// Constructor
public SmsProxy() {
super();
}

// Handle creation options
@Override
public void handleCreationDict(KrollDict options) {
super.handleCreationDict(options);

if (options.containsKey("messageBody")) {
messageBody = (String)options.get("messageBody");
}

if (options.containsKey("recipient")) {
recipient = (String)options.get("recipient");
}
}

@Kroll.method
public void send()
{
// send the message
}
}


Events
Notify a change of state, or an asynchronous event

// create the Module object
var tibarcode = require('ti.barcode');

var scanner = tibarcode.createScanner();

// success event listener
scanner.addEventListener('success', function(e) {
var code = e.barcode;
var type = e.type;
alert('Found code: ' + code + ' type: ' + type);
});


Events

@implementation TiBarcodeScannerProxy

// Scanner Delegate

- (void) imagePickerController: (UIImagePickerController*)reader
didFinishPickingMediaWithCode:(NSString*)code andType:(NSString*)type
{
if ([self _hasListeners:@"success"]){
NSDictionary *results = [NSDictionary dictionaryWithObjectsAndKeys:
code, @"code", type, @"type", nil];

[self fireEvent:@"success" withObject:results];
}
}

@end


Events

public class ScannerProxy extends KrollProxy
{
void onScannerResult(String code, String type)
{
if (hasListeners("success")) {
KrollDict event = new KrollDict();
event.put("code", code);
event.put("type", type);
fireEvent("success", event);
}
}
}


Callbacks
Notify the result of an asynchronous action

// let's not freeze on huge xml data
xml2json.convertAsync(xmlDoc, function(data) {
Ti.API.info("JSON object: " + JSON.stringify(data.json));
});


Callbacks

-(void)convertAsync:(id)args
{
ENSURE_ARG_COUNT(args, 2);

id xml = [args objectAtIndex:0];
KrollCallback *cb = [args objectAtIndex:1];
ENSURE_TYPE(cb, KrollCallback);

//pass just the first (string|blob) arg to convertXml()

dispatch_async(dispatchQueue, ^(void) {
id result = [self convertXml:xml];
NSDictionary *cbArgs = [NSDictionary dictionaryWithObject:result forKey:@"json"];

[self _fireEventToListener:@"success" withObject:cbArgs listener:cb
thisObject:nil];
});
}


Callbacks

@Kroll.method
public KrollDict convertAsync(String xml, final KrollFunction callback)
{
new Thread() {
@Override public void run() {


KrollDict data = new KrollDict();
event.put("json", json);
callback.call(getKrollObject(), data);
}
}.start();
}


ViewProxy
Manages the
Holds the state
native view
of a view
hierarchy

Methods

Native Views
ViewProxy

Hierarchy
Properties

View
(get/set)

Events


ViewProxy
Manages the
Holds the state
native view
of a view
hierarchy

Methods

Native Views
ViewProxy

Hierarchy
Properties

View
(get/set)

Events

JS THREAD


ViewProxy
Manages the
Holds the state
native view
of a view
hierarchy

Methods

Native Views
ViewProxy

Hierarchy
Properties

View
(get/set)

Events

JS THREAD UI THREAD


ViewProxy
Manages the
Holds the state
native view
of a view
hierarchy

Methods

Native Views
ViewProxy

Hierarchy
Properties

View
(get/set)

Events

JS THREAD UI THREAD

Mostly async


Super-Smooth TableView

• API
• createMessagesView(properties);
• setMessages([]messages);
• insert(message);
• addEventListener(‘click’, callback);


Implementation
MessagesViewProxy

TiSmoothMessagesViewProxy.h
@interface TiSmoothMessagesViewProxy : TiViewProxy

@property (nonatomic, retain) MessagesCollection *msgs; //model

@end

TiSmoothMessagesViewProxy.m
@implementation TiSmoothMessagesViewProxy

@synthesize msgs;

//other methods

-(void) insert:(id)args
{
ENSURE_SINGLE_ARG(args, NSDictionary);
[self.msgs insertMessageOnTop:[self messageFromDictionary:(NSDictionary*)args]];

[self makeViewPerformSelector:@selector(addMessage:) withObject:args createIfNeeded:YES
waitUntilDone:NO];
}

@end


Implementation
MessagesViewProxy

TiSmoothMessagesViewProxy.h
@interface TiSmoothMessagesViewProxy : TiViewProxy

@property (nonatomic, retain) MessagesCollection *msgs; //model

@end

TiSmoothMessagesViewProxy.m
@implementation TiSmoothMessagesViewProxy

@synthesize msgs;

//other methods

-(void) insert:(id)args
{
ENSURE_SINGLE_ARG(args, NSDictionary);
[self.msgs insertMessageOnTop:[self messageFromDictionary:(NSDictionary*)args]];

create the view and call addMessage on the UI thread
[self makeViewPerformSelector:@selector(addMessage:) withObject:args createIfNeeded:YES
waitUntilDone:NO];
}

@end


Implementation
MessagesView
TiSmoothMessagesView.h
@interface TiSmoothMessagesView : TiUIView
{

MessagesViewController *viewController;
}

@end

TiSmoothMessagesView.m
@implementation TiSmoothMessagesView

-(void)initializeState
{
[super initializeState];
viewController = [[InboxViewController alloc] initWithStyle:UITableViewStylePlain];

UITableView *tableView = viewController.tableView;

[self addSubview:tableView];
}

-(void)addMessage:(InboxMessage*)message
{
ENSURE_UI_THREAD(addMessage, message);
[viewController addMessageOnTop:message];
}

-(void)frameSizeChanged:(CGRect)frame bounds:(CGRect)bounds
{
[TiUtils setView: viewController.tableView positionRect:bounds];
}

@end


Implementation
MessagesView
{

}

@end


-(void)initializeState called by Titanium at view creation
{


}

{
}

{
}

@end


Implementation
MessagesView
{

}

@end


-(void)initializeState called by Titanium at view creation
{


}

{
}

called by Titanium for notifying a
{ change in frame size
}

@end


module.xcconfig
//
// PLACE ANY BUILD DEFINITIONS IN THIS FILE AND THEY WILL BE
// PICKED UP DURING THE APP BUILD FOR YOUR MODULE
//

OTHER_LDFLAGS=$(inherited) -framework AVFoundation
-framework CoreMedia -framework CoreVideo -framework QuartzCore
/usr/lib/libiconv.dylib

build &
package

Module Package
(.zip)

app bundle

timodule.xml
<?xml version="1.0" encoding="UTF-8"?>
<ti:module xmlns:ti="http://ti.appcelerator.org" xmlns:android="http://schemas.android.com/apk/res/android">
<iphone>
</iphone>
<android xmlns:android="http://schemas.android.com/apk/res/android">
<manifest>
<uses-permission android:name="android.permission.SEND_SMS" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<application>
<activity android:name="ti.conf.sample.MyCustomActivity">
</activity>
</application>
</manifest>
</android>
<mobileweb>
</mobileweb>
</ti:module>

build &
package AndroidManifest.xml

Module Package
(.zip)

app.apk

Debugging


Create a debug build
$ sed s/Release/Debug/ build.py > build_debug.py

build.py
168: rc = os.system("xcodebuild -sdk iphoneos -configuration Release")
171: rc = os.system("xcodebuild -sdk iphonesimulator -configuration Release")

build_debug.py
168: rc = os.system("xcodebuild -sdk iphoneos -configuration Debug")
171: rc = os.system("xcodebuild -sdk iphonesimulator -configuration Debug")


Debugging


Debug Logs
@Kroll.module(name="Ticonfsample", id="ti.conf.sample")
public class TiconfsampleModule extends KrollModule
{

// Tag for debug log messages
private static final String LCAT = "TiconfsampleModule";

// tells if debug logging has been enabled in the Titanium application
private static final boolean DBG = TiConfig.LOGD;

@Kroll.method
public void doSomething()
{
Log.d(LCAT, "doing something");
}
}


Android DDMS


Thank you!


Extending Titanium with native iOS and Android modules

More Related Content

What's hot

Viewers also liked

Similar to Extending Titanium with native iOS and Android modules

Recently uploaded

Extending Titanium with native iOS and Android modules