Extending Titanium Native iOS & 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 Native iOS & Android Modules

Recomendados

Recomendados

Más contenido relacionado

La actualidad más candente

La actualidad más candente (18)

Destacado

Destacado (20)

Similar a Extending Titanium Native iOS & Android Modules

Similar a Extending Titanium Native iOS & Android Modules (20)

Último

Último (20)

Extending Titanium Native iOS & Android Modules