My Getting Started Experience/Tutorial with Appcelerator Titanium 2.0 and Appcelerator Cloud Services (formerly known as CocoaFish)

First, I am a complete newbie when it comes to Appcelerator though I am comfortable with JavaScript and cloud related technologies.  I have spent time with Azure (C# via Visual Studio), Cloud Foundry, Heroku, Google App Engine, Amazon's Beanstalk and of course Red Hat's OpenShift as PaaS (platform-as-a-service) offerings.
And I have been able to start digging into various client-side development technologies like jQuery Mobile + PhoneGap/Apache Cordova (see Kris' article) and just recently I tried out some Objective-C via XCode and the fantastic Kinvey quickstart tutorial.

Recently, I have had several people I know and respect tell me that Appcelerator Titanium is the best solution for cross-platform mobile application development, it uses JavaScript as its primary language therefore the average jQuery front-end to Java back-end guy like myself should be able to learn it easily.  Plus, Appcelerator Titanium is based on Eclipse which is something I have spent a lot of time with for my JBoss "day job" as evidenced by all kinds of screencasts.

My specific interest in mobile is mostly related to how to communicate with a "backend" - and now it seems the term "BaaS" for backend-as-a-service is starting to become more popular with several offerings now available such as Parse, Kinvey, and StackMob.   The primary difference between a BaaS vs a PaaS is that BaaS assumes the developer wishes to focus only on his/her client-side code written in Objective-C, Android Java, JavaScript,  HTML5 + a JS lib (e.g. Backbone) - all the user management, data & blob storage, push notifications, etc are all managed through a client-side API and a web console.  In other words, a BaaS has no server-side coding to worry with.   A PaaS on the other hand, assumes the developer wishes to write custom server-side logic in PHP, Perl, Java, JavaScript for Node.js, etc.

On April 17. 2012, Appcelerator announced Titanium 2.0 where the most important feature (IMHO) is integration with the recently acquired CocoaFish - cloud services for the mobile developer, now called Appcelerator Cloud Services.

And here it is April 21st and I decided to spend my Saturday giving it a try and writing up this blog. :-)

Keep in mind that my primary goal is to be able to store & retrieve data associated with my mobile application "in the cloud" and ideally, share data between multiple instances (multiple devices) of my application.  Unfortunately, that particular use case does not have a tutorial and what follows are the basic steps that I followed to get some simple things working.

Note: There are a few documents that I found to be useful:

Quickstart

Integrating with Appcelerator Cloud Services

API Docs

and there are some examples that are installed on your local machine.  In the case of a Mac, you might be able to find them at:

$HOME/Library/Application Support/Titanium/modules/commonjs/ti.cloud/2.0.1/example

For this particular weekend (April 21st),  I was unable to find a "from scratch" tutorial, so I had to dig around and follow some hunches.   Hopefully this blog post inspires the good folks at Appcelerator to provide a nice getting started/tutorial for ACS with a Titanium client application.

1) Register at Appcelerator.com - this was a little bit tricky, I had originally went to "cocoafish.com" which redirected me to http://www.appcelerator.com/cloud and from there I clicked on the Start Using Cloud Services For Free button.  This was a bit awkward as it had me fill in a form and await an email verification, it then would ask me to login, sign-up, login again.  After about four attempts at the login it seemed to feel that I belonged and settled down.  It could be I was just trying to move to fast for the system.  Preserving pays off - just login a couple of more times. :-)  Why did I start with "cocoafish"? Because I did not read the press release until after I attempted to sign up, so I did not really know what the new name/website was.

2) Download Titanium Studio - I won't bore you with the details of download & installation as it is very straightforward - and I had previously installed Titanium Studio but never really used it - so upon launching it this past Friday night - it automatically knew the 2.0 update was ready - I just followed the typical Eclipse update process and was painlessly upgraded.  I do believe you will need XCode and the iOS SDK installed on your machine as well and I already had that installed from previous attempts at using PhoneGap and Objective-C.

3) Back at the ACS web console, I created a ACS only application called ToDo - why did I choose ACS only and name it ToDo?  I really cannot say, it was somewhat random and "felt right".

Then I went back to Titanium Studio to begin the development project - perhaps it was possible to create the ACS App from within Studio but I did not/have not notice it - so my process is to build both halves, client & server and then connect the two.

4) File -> New -> Titanium Mobile Project

Project name: CloudUsers (note: screenshot shows CloudUsers2 because I ran through this twice)
App Id: com.yourcompany.cloudusers (note: I am Java guy so I used a "package name")
Company/Personal URL: http://www.yourcompany.com
and Automatically cloud-enable this application should be checked by default.

Select Next

Select Single Window Application

and Select Finish

Note: After working with several cloud offerings, I was expecting that the New wizard would prompt me for my ACS app - ideally provide a list of the apps described in the ACS web console.   The next step is how I addressed this disconnect between my client-side app and the ACS service.

5) Edit tiapp.xml to inject your ACS App's keys.  You will wish to match up the various ACS keys with what is in the web console.  Unfortunately, the web console and this XML file have slightly different names for each key - that can be an issue for the newbie.

"acs-api-key-development"= APP Key

Note: double clicking on the APP Key data does not highlight it correctly in the web console.   So be a little cautious with your highlight to copy & paste - double clicking tends to also grab the string "Key".

In the top right-hand corner of the web console, there is an option for PRODUCTION and DEVELOPMENT, make sure DEVELOPMENT is selected for the "acs-api-key-development" property. Then click on PRODUCTION to get it's APP Key.

Click on Show OAuth Credentials

"acs-oauth-key-development"= OAuth Consumer Key
"acs-oauth-secret-development" = OAuth Secret

You can follow the same basic steps to get the Production keys.

Save your changes to tiapp.xml 

6) Create some users, you can not create data (custom objects) without first having a user.   Open up ui/common/FirstView.js and modify it so you have several textfields and a button - to create a new user.  First, declare the Cloud variable to interact with ACS:

var Cloud = require('ti.cloud');

Cloud.debug = true;

I placed these lines directly inside of "function FirstView", perhaps they should have gone elsewhere but I am brand new to Appcelerator and it worked fine in this location.

Then add a series of textfields, I found that if you type in "text" and hit Control-Space, Titanium Studio will then drop in a generic declaration of a Ti.UI.createTextField block as well as an eventlistner.  This is a tremendous aid to developer productivity.  Just note that there are some odd things about this content assist feature:

a) A textfield comes with the following property set:

softKeyboardOnFocus : Ti.UI.Android.SOFT_KEYBOARD_DEFAULT_ON_FOCUS

which causes a runtime error in the iOS simulator, you will need to comment it out.

Ideally, Titanium Studio would recognize that my project is not setup for Android and would leave that property out.

b) Any component added via this trick "text" with Control-Space or "button" with Control-Space, creates a particular line of code to add the component to the overall "window":

parentView.add(componentName);

"parentView" needs to be changed to "self" for these Single Window Applications.

c) If you use "button" and Control-Space, it creates a button with myHeight, myWidth, myTop and myLeft - those are not valid values - you will need to change them to numbers.  Leaving those variable names in your project will result in a nice big red error message.

The fields you need for a new user form are:

username

password

password_confirmation

first_name
last_name
email

and then you will need a button, in my case, I called it "Create"

    // Listen for click events.
    Create.addEventListener('click', function() {
        Cloud.Users.create ({
            username: userNameField.value,
            password: passwordField.value,
            password_confirmation : passwordConfirmation.value,
            first_name: firstName.value,
            last_name: lastName.value,
            email: emailAddress.value
        }, function (e) {
            if (e.success) {
                alert('Success');
            } else {
                alert('Fail');
            }
        });
    });

Complete listing

7) Test - Hitting the small green arrow in the Titanium Studio toolbar will launch the iOS Simulator (on a Mac, not sure what happens on a Windows machine).

Enter some data in the fields that should be valid and hit the Create button, I am not sure if invalid data (e.g. poorly formed email address) will be rejected by ACS.  

And then check out the ACS web console for your application - as you create new users.

and drill-down on "Users"

Like magic, your  mobile application's, client-side code is able to modify server-side resources - with no server-side coding required.

8) Now that you have some users in the system, you can create custom objects with the following block of code:

  label.addEventListener('click', function(e) {
    Cloud.Users.login({
      login  : 'username3',
      password: '123password',
    }, function(e) {
      if (e.success)   {

        Cloud.Objects.create({
          classname : 'cars',
          fields : {
            make : 'Ford',
            color : 'green',
            year : 2010
          }
        }, function(e) {
          if(e.success) {
            var car = e.cars[0];
            alert('Success:\\n' + 'id: ' + car.id + '\\n' + 'make: ' 
            + car.make + '\\n' + 'color: ' + car.color + '\\n' + 'year: ' 
            + car.year + '\\n' + 'created_at: ' + car.created_at);
          } else {
            alert('Create Error:\\n' + ((e.error && e.message) || JSON.stringify(e)));
          }
        }); // Cloud.Objects.create
                    
      } else {
        alert('Login Error:\\n' +
                ((e.error && e.message) || JSON.stringify(e)));
      } 
    }); // Cloud.Users.login
    
  }); // label.addEventListener

And the result of running this code will create new custom objects which are visible in the ACS web console.

and when you drill-down on Custom Objects

Now, one trick that I use is to start new projects to test out new things.  In the case of adding a custom object, I made yet another Titanium Mobile Project following the same steps as the one for CloudUsers.

Warning: If you do not first login then you will receive a runtime error of "401: You need to sign in or sign up before continuing" 

This error message can be a real head scratcher.   Searching in Appcelerator's Q&A (pitiful attempt at forum) does not yield great results (I have a screenshot of that as well).   It is also funny that the documentation tells you how to put in the Error message but the result has the "\n" in the string.   

9) Querying for the custom objects does not actually require a user/login - I was able to query in a completely different project using the following block of code in FirstView.js

function FirstView() {
  //create object instance, a parasitic subclass of Observable
  var self = Ti.UI.createView();
  var Cloud = require('ti.cloud');
  Cloud.debug = true;
  
  // Create a Button.
  var Query = Ti.UI.createButton({
    title : 'Query Cars',
    height : 35,
    width : 100,
    top : 50
  });
  
  // Listen for click events.
  Query.addEventListener('click', function() {
    Cloud.Objects.query({
      classname: 'cars',
      page: 1,
      per_page: 10
    }, function(e) {
      if (e.success) {
        alert('Success:\\n' +
                'Count: ' + e.cars.length);
      } else {
           alert('Error:\\n' +
                ((e.error && e.message) || JSON.stringify(e)));        
      } // else - fail
    }) // Cloud.Objects.query
  });
  
  // Add to the parent view.
  self.add(Query);
  
  return self;
}

With this level of effort, one real day of digging in, including writing up this long blog post. I think I could finish my little application with Appcelerator.   My 14 year old son is more interested in using Objective-C and ACS does have a iOS SDK for that style of development.   You might see a future blog post where we compare our experiences with building a mobile based apps using both Objective-C and Appcelerator with the same backend services.

Project Sources

Adding ACS Users at Github

Adding ACS Custom Objects at Github

Why did I put all of this into a blog?  I may not get back to looking at ACS and Appcelerator Titanium for several days or weeks - so this posting will help jog my memory and it might be useful for someone else who is trying to get started with Appcelerator Cloud Services.