Extending Appcelerator Titanium Mobile through Native Modules

1. ExtendingTitanium Mobile through Native Modules Olivier Morandi

2. # whoami Olivier Morandi Freelance mobile developer & software engineer olivier.morandi@gmail.com @olivier_morandi https://github.com/omorandi

3. Titanium Mobile A set oftoolsfordevelopingcross-platform mobile applications in JavaScript iOS (iPhone/iPod/iPad) Android Blackberry(through a commercial subscription) http://www.appcelerator.com https://github.com/appcelerator/titanium_mobile

4. Anatomyof a project Project directory build/ android/ iphone/ Resources/ app.js manifest tiapp.xml Buildfolders, per platform Resourcefiles: JS code, images, sounds, SqliteDBs, etc. Project files

5. manifest #appname: whymca #publisher: olivier #url: http://www.whymca.org #image: appicon.png #appid: com.whymca.test #desc: undefined #type: mobile #guid: 746e9cb4-49f6-4afe-af0b-5de9f0116f65

6. tiapp.xml <?xml version="1.0" encoding="UTF-8" standalone="no"?> <ti:appxmlns:ti="http://ti.appcelerator.org"> <deployment-targets> <target device="iphone">true</target> <target device="ipad">false</target> <target device="android">true</target> </deployment-targets> <id>com.whymca.test</id> <name>whymca</name> <version>1.0</version> <publisher>olivier</publisher> <url>http://www.whymca.org</url> <description>notspecified</description> <copyright>2011 byolivier</copyright> <icon>appicon.png</icon> <persistent-wifi>false</persistent-wifi> <prerendered-icon>false</prerendered-icon> <statusbar-style>default</statusbar-style> <statusbar-hidden>false</statusbar-hidden> <fullscreen>false</fullscreen> <navbar-hidden>false</navbar-hidden> <analytics>false</analytics> <guid>746e9cb4-49f6-4afe-af0b-5de9f0116f65</guid> <iphone> <orientationsdevice="iphone"> <orientation>Ti.UI.PORTRAIT</orientation> </orientations> <orientationsdevice="ipad"> <orientation>Ti.UI.PORTRAIT</orientation> <orientation>Ti.UI.UPSIDE_PORTRAIT</orientation> <orientation>Ti.UI.LANDSCAPE_LEFT</orientation> <orientation>Ti.UI.LANDSCAPE_RIGHT</orientation> </orientations> </iphone> <androidxmlns:android="http://schemas.android.com/apk/res/android"> </android> <modules> </modules> </ti:app>

7. app.js (1) varwin = Titanium.UI.createWindow({ title:'Hello', backgroundColor:'#fff' }); var label1 = Titanium.UI.createLabel({ color:'#333', text:’Hello World!', textAlign: 'center', font: {fontSize: 30, fontWeight: 'bold'} }); win.add(label1);

8. app.js (2) varbt = Titanium.UI.createButton({ title: 'Click me', width: 100, height: 40, bottom: 40 }) bt.addEventListener('click', function(e) { label1.text = 'WHYMCA ROCKS!'; }); win.add(bt); win.open();

9. UI widgetscreated in JS are mapped on the native componentsof the target platform

10. Appdistribution The productreadyfordistributionisactually a native app JS Code Partiallycompiled and optimized Packed in binary format into the bundle Resources Copiedinto the bundle

11. Developmenttoolchain Ti Studio (IDE) Ti Developer (toolchain GUI) Ti SDK toolchain (Pythonscripts) Xcode/iOS SDK Android SDK Mac OSX Windows Linux Mac OSX

12. ApplicationStack JavaScriptApplication Code TitaniumJavaScript API Android Modules iOS Modules JS Interpreter JS Interpreter TitaniumFramework Runtime Runtime Android SDK iOS SDK

13. Ti JavaScript API UI Titanium.UI Titanium.UI.Android Titanium.UI.Clipboard Titanium.UI.iOS Titanium.UI.iPad Titanium.UI.iPhone Titanium.Map Sensors Titanium.Accelerometer Titanium.Geolocation Titanium.Gesture Networking Titanium.Network Titanium.XML Titanium.Facebook Titanium.Yahoo Titanium.Analytics Device integration Titanium.Platform Titanium.Contacts Titanium.Media Titanium.Android Titanium.Android.Calendar Titanium.Android.NotificationManager Titanium.App.iOS Titanium.App.Android Data Persistence Titanium.Database Titanium.Filesystem Titanium.App.Properties i18n Titanium.Locale Utilities/helpers Titanium Titanium.App Titanium.API Titanium.Utils http://developer.appcelerator.com/apidoc/mobile

14. Extending the API:why? Accessingspecific OS features Leveragingexisting native libraries Optimizingcriticalportionsof the app Extending/amelioratingportionsof the Titanium Mobile framework

15. Extending the API:how? Creating a forkofTitanium Mobile’ssource code on github Unflexibleapproach You put yourhands in the heartof the framework Maintaining a separate branch can betedious and costly There are situationswherethisis the cheaperapproach E.g. whenneedingtoextend the functionalityofcoremodulesof the framework (networking, maps, ecc.)

16. Extending the API:how? Creatingone or more native modulesthrought the TitaniumModule SDK Great flexibility Easy todistributeas Open Source Binarypackages AppceleratorTi+PlusMarketplace (?)

17. Moduli nativi– some examples Androidbarcode scanner (Zxingwrapper) https://github.com/mwaylabs/titanium-barcode iOSZipFile(create/decompress zip files) https://github.com/TermiT/ZipFile iOSTiStoreKit (in apppurchase) https://github.com/masuidrive/TiStoreKit iOSTiSMSDialog (in app sms sending) https://github.com/omorandi/TiSMSDialog AppceleratorTitaniummodules(sample modules) https://github.com/appcelerator/titanium_modules

18. Titanium JS Interface varbt = Titanium.UI.createButton({ title: 'Click me', width: 100, height: 40, bottom: 40 }); bt.addEventListener('click', function(e) { label1.text = 'WHYMCA ROCKS!'; });

19. Titanium JS Interface Module Titanium.UI Object Titanium.UI.Button ObjectFactory Titanium.UI.createButton() Propertygetters/setters - methods Button.title Button.width Button.animate() Ecc. Eventhandling Button.addEventListener()

20. ModuleArchitecture Object Objectproperty/method Namespace Titanium.UI Titanium.UI.Button Titanium.UI.Button.width JavaScript Module Proxy setters/getters Methods Events setters/getters Methods Events Internal State Internal State Titanium abstraction Implementation Factory Proxy Class ModuleClass

21. The pathtomoduledevelopment Define the functionality you need to be exposed and how they’ll be invoked from JavaScript code  define the API of the module Create a project with the toolsof the Module SDK Implement the API Build-Test-Debug

22. Case Study–iOS SMS module The Titanium API providesemailsendingfunctionalitythrough the Ti.UI.EmailDialogcomponent, butnothingforsending SMS messages On iOSthisfeatureisavailablesinceversion 4.0 of the OS through the MFMessageComposeViewControllerclass

23. MFMessageComposeViewController

24. Case Study–iOS SMS module Implement a native modulecapableofexposing the featuresof the MFMessageComposeViewControllerclassthrough a JavaScript API: Check the availabilityof the component (notpresent in iOSversions < 4.0) Programmatically set recipients and message body Set UI properties (e.g. navbar color) Notify the callerabout the resultof the sendoperation

25. Resources Module SDK Docs Android http://wiki.appcelerator.org/display/guides/Module+Developer+Guide+for+Android iOS http://wiki.appcelerator.org/display/guides/Module+Developer+Guide+for+iOS Titanium Mobile source code https://github.com/appcelerator/titanium_mobile Code ofothermodulesreleasedas open source

26. 1.Defining the API Object SMSDialog Properties recipients messageBody barColor Methods isSupported() open()

27. Example code varsmsDialog = module.createSMSDialog(); if(smsDialog.isSupported()) { smsDialog.recipients = [’+14151234567']; smsDialog.messageBody = 'Test messagefrom me'; smsDialog.barColor = ’red'; smsDialog.addEventListener('complete', function(e){ Ti.API.info('Result: ' + e.resultMessage); }); smsDialog.open({animated: true}); }

28. Result

29. 2.Creating the project # titanium create --platform=iphone --type=module --dir=~/ --name=SMSDialog --id=com.whymca.smsdialog

30. titanium (alias) Mac OS X alias titanium="/Library/Application Support/Titanium/mobilesdk/osx/1.7.0/titanium.py" Linux alias titanium="$HOME/Library/Application Support/Titanium/mobilesdk/osx/1.7.0/titanium.py" Windows XP PATH=C:Documents and SettingsAll UsersApplication DataTitaniummobilesdkwin321.7.0 Windows Vista/7 PATH=C:ProgramDataTitaniummobilesdkwin321.7.0

31. Xcode project generated assets/ Classes/ ComWhymcaSmsdialogModule.h ComWhymcaSmsdialogModule.m ComWhymcaSmsdialogModuleAssets.h ComWhymcaSmsdialogModuleAssets.m example/ app.js build.py ComWhymcaSmsdialog_Prefix.pch manifest module.xcconfig smsdialog.xcodeproj titanium.xcconfig Assetfilestobedistributedwith the module Implementationfiles Tobefilledwithour code Sample programfortestingmoduleinvocations Script for building and packaging the module Metadataformanaging the module in Titanium Include/linkingdirectivesused at integration-time Include/linkingdirectivesused at build-time

32. 3.Implementation The generated project alreadycontains the classthatimplements the module: ComWhymcaSmsdialogModule The classnameis a CamelCasetranspositionof the moduleidchosenwhencreating the project In JSitwillbeinstantiatedas varmodule = require(‘com.whymca.smsdialog’);

33. Implementing the proxy The SMSDialogobjectwedefined, mustbeimplementedas a proxy The nameof the classmustfollow a convention similartothatusedfor the modulename, in the form: <moduleID><proxyName>Proxy i.e. ComWhymcaSmsdialogSMSDialogProxy

34. SMSDialogProxyclass Mustbe a subclassof the TiProxyclass Itshouldexposeproperties and methodsthatwewanttomakeavailabletoJavaScript code

35. Objectcreation and initialization varsmsDialog = module.createSMSDialog(); smsDialog.recipients = [’+391234567']; smsDialog.messageBody = 'Test message'; //or varsmsDialog = module.createSMSDialog({ recipients: [’+391234567’], messageBody: 'Test message’ });

36. Creation Objectcreationiscompletelymanagedby the framework The JS construct module.create<ProxyName>() ismapped on code thatinstantiateanobjectof the correctclassthanksto the naming convention used

37. Initialization The object can beinitializedeitherpassing a dictionaryofpropertyvaluesto the factorymethod, eithersetting single propertyvalues in a second moment through dot notation In either case, if the proxydoesn’texplicitlyprovidegetter/setter methodsforthoseproperties, they are automaticallyinserted in the dynpropsdictionaryof the proxyobject

38. Initialization It’salwayspossibletoretrievepropertyvaluespresent in the dynpropsdictionarywith the message [self valueForUndefinedKey:@"messageBody"]

39. Conversion utilities The frameworkprovides the TiUtilsclass, whichcontainsmethodsforsimplifying the conversionofvaluescomingform JS code: NSString * messageBody = [TiUtilsstringValue:[self valueForUndefinedKey:@"messageBody"]]; UIColor * barColor = [[TiUtilscolorValue:[self valueForUndefinedKey:@"barColor"]] _color]; BOOL animated = [TiUtilsboolValue:@"animated" properties:argsdef:YES];

40. Methods They are exposedtoJavaScriptbysimplydeclaringthem in the @interfacesectionof the proxyclass Theymustbedeclared in oneof the followingforms: -(id)methodName:(id)args -(void)methodName:(id)args

41. Example @interfaceComWhymcaSmsdialogSMSDialogProxy: TiProxy <MFMessageComposeViewControllerDelegate> - (id)isSupported:(id)args; - (void)open:(id)args; @end

42. Methodarguments The listofargumentspassed in JavaScriptto a methodispassedas a NSArrayobject in the argsparameter The frameworkprovides some Cmacrosfor the caseswhere a single argumentisexpected: ENSURE_SINGLE_ITEM(args,type) ENSURE_SINGLE_ARG_OR_NIL(args, type)

43. PassingJavaScriptdictionaryObjects JS: smsDialog.open({animated: true}); OBJ-C: - (void)open:(id)args { ENSURE_SINGLE_ARG_OR_NIL(args, NSDictionary); //args ora è un NSDictionary BOOL animated = [TiUtilsboolValue:@"animated" properties:argsdef:YES]; //[…]

44. Returnvalues The types NSString NSDictionary NSArray NSNumber NSDate NSNull don’tneedtobeconverted Numerictypesmustbewrapped in a NSNumberobject It’spossibletoreturnproxyobjects (thoughtheymustbeautoreleasedifallocatedbyourmethod) return [[[TiColor alloc] initWithColor:colorname:@"#fff"] autorelease];

45. Executing a method in the UI thread There are caseswhere a methodshouldbeexecuted in the UI thread (e.g. wheninteractingwithuser interface objects) In suchcaseswe can use the macro ENSURE_UI_THREAD(method,args) for forcing the executionof the methodon the UI thread

46. Events The simplest way a proxyhastointeractwith JS code isthroughevents In JS weregisteranevent-listenerfunction on a specificeventmanagedby the proxy Example JS: smsDialog.addEventListener('complete', function(e){ Ti.API.info('Result: ' + e.resultMessage); });

47. Events OBJ-C: -(void)_listenerAdded:(NSString*)typecount:(int)count { //type = @"complete" } -(void)_listenerRemoved:(NSString*)typecount:(int)count { //type = @"complete" }

48. Events OBJ-C: NSDictionary*event = [NSDictionarydictionaryWithObjectsAndKeys:resultMessage, @"resultMessage", nil]; [self fireEvent:@"complete" withObject:event];

49. 4. Build We can build the project directlyfromXcode Usefulforchecking out warning & syntaxerrormessages

50. ⌘B

51. 4. Build Using the script # build.py from the module project root directory Itperforms a complete build and itpackages the modulelibrary + assets + metadata in a zip file

52. Package Name in the form com.whymca.smsdialog-iphone-0.1.zip Forbeinguseditmustbedecompressed in the directory /Library/ApplicationSupport/Titanium/

53. Simpletesting Byexecuting the script # titaniumrun in the project directory Thiswill create a temporary project based on the app.js file from the exampledirectory Not the best way fortesting the module

54. Using the module in a Ti Mobile Project <?xml version="1.0" encoding="UTF-8" standalone="no"?> <ti:appxmlns:ti="http://ti.appcelerator.org"> <!–-SNIP…--> <modules> <moduleversion=“0.1” platform=“iphone”> com.whymca.smsdialog </module> </modules> </ti:app> tiapp.xml

55. Testing/Debugging Create a new Ti Mobile project with test code and a referenceto the module Launch the app at leastonetimefrom Ti Studio/Developer Open the Xcode project from the build/iphonedirectory found in the app project directory IssueBuild&Debugfromthere Set breakpoints in the module code, test, etc.

57. Thankyou! Anyquestions? You can findall the code usedforthispresentation on https://github.com/omorandi/whymca-conf-2011