Very basic Appcelerator tutorial

Appcelerator is a toolkit/API that allows you to build almost native apps for Android, iPhone, iPad and Blackbery mobile devices.

When learning anything new, you need to be prepared to invest some time and do your homework/research. The aim of this post is to try and help people who may be interested in getting to grips with the basics of Appcelerator Titanium Studio.

Before we can get started you will need to set up your development environment. This greatly depends on what type of system you are using and what your target device is. For example if you want to build apps for iOS you will need to have a Mac. This is because you will need access to the iPhone/iPad emulator. If you are interested in developing apps for Android you can use Windows, Mac or Linux.

To develop for Blackberry you will need to have access to a Windows machine. This is because the Blackberry emulators (at time of writing) are all windows .exe files. You may be able to run the emulator under Linux or Mac using something like "Wine" but I have not tested this.

You will need to download Appcelerator Titanium Studio...
And the SDK for the platform(s) you intend to develop for. You can obtain the latest version of the Google Android SDK (Software development kit) from the Android developers website.

The Apple iOS SDK is also available for download, although you will need to register as an Apple developer (not free) on order to obtain the SDK.

Once you have downloaded and installed Appcelerator Titanium Studio and your chosen SDK(s) you are ready to install and configure your development environment.

In order to use Appcelerator you will need to register as an Appcelerator developer. Membership to the Appcelerator network is free if you are a single user wishing to build apps. You may be required to purchase a license if you are a commercial user. When logged in you will have immediate access to download Appcelerator Titanium studio and have access to all the relevant documentation.

I will not go into any great detail here about the actual install process because Appcelerator do a great job of this within their own website. You can read about installing Appcelerator Titanium studio here.

Once you have carried out a full install of Appcelerator and the required SDK (Android, iOS and/or Blackberry) you are now ready to make a start on your first app.

By going this far and deciding to learn about building an app, you probably have an idea in mind for and app you want to build. I suggest forgetting your idea(s) for now and just concentrate on getting to know the layout of Appcelerator and give yourself time to get to grips with the basics before you dive in at the deep end and try to actually create your app.

The Appcelerator Titanium screen after login

 This image represents what you see when you first run Titanium. The main screen on display is the dashboard. This is a section of web based content that keeps you up to data with whats happening with Appcelerator. To the right we have two views (black) this is where you will later view and manage your files within your applications and projects. at the top we also see the conventional menus that allow you to access various features and tools from Titanium studio. I suggest you spend a little bit of time getting familiar with the the software so you will better know your way around it.

To start a new project simple click...
File > New > Titanium Mobile Project

When you do this it will present you with a new screen asking you for information about your project.

The Titanium new project window

The project name can be anything you want. Because you are new and just testing the software I suggest giving it a name to reflect this, something like "testapp" will do for now. Within the project settings section you will need to declare an app id. This takes the form of...
com.yourname.appname
Once you have specified this value you should then select what SDK and version you are targeting your app for. In this case I have selected to target my app at android. Had I been using a Mac I could have also chose to target iOS devices such as iPad, iPod and iPod touch. Once you have filled out all required fields you can then press finish and Appcelerator Titanium will initialize your new project.

The display will now have three tabs. app.js, Dashboard and tiApp Editor. The dashboard tab will still be the main intro dashboard so you can safely close this tab. app.js is the main javascript file for your new project and tiApp Editor will allow you to edit settings you specified when creating your new mobile application. You can close tiApp Editor if you are happy with the details you previously provided. You can open these tabs again simply by selecting them from the files now displayed at the left side of the interface.

At this point it might be a good idea to run a quick test on your Titanium studio setup. What I suggest is running a very quick test just to make sure everything is working as it should. From the very top of the interface click the green arrow button. This will build your project and open it in your emulator. If you have installed more than one SDK you will need to choose from the drop down box what emulator you want to run. If all goes well your system will compile the application and open the emulator displaying a blank app. Now its time to make our app do something. When I say blank app you will have 2 tabs displayed. This is just some sample code that Appcelerator adds when you create a new project.

Now lets return to the IDE and view our main application file (app.js).

What I then do is remove all code except for the opening line that specifies the default background color for our application...

Titanium.UI.setBackgroundColor('#000');

We will now start writing some code to build a very quick and simple app. We aren't going to do anything fancy. We will just create an app with a button. When we press the button we will display some text within the app.

what we first need to do is create a window. A window is like a page. We can place objects into our window. The first thing we need to do is declare the window...

var window1 = Titanium.UI.createWindow({
   
})

This piece of code will create a window that can be accessed within our application.  What we now want to do is creat a button and place it onto our window...

var button1 = Titanium.UI.createButton({

title:'Press me'

})
window1.add(button1);

The code above created a new object 'button1' and in the final line of code we add the button to our window (window1). You will notice we also added some attributes to the button.

Now we need to place another object onto our window that will allow us to enter text. For this we will use a 'label' first of all lets declare it within our code...

var warninglabel = Titanium.UI.createLabel({ 

})

you will notice that we declared the label, but did not give it any attributes. What we can do is provide it with a default value by adding the following...
text:'press the button'

full window declaration and inclusin into our window...

var warninglabel = Titanium.UI.createLabel({
    text:'press the button'
})
window1.add(warninglabel);

You could run the app at this stage by adding the following code to the bottom of your file
window1.open();

This tells Appelerator to open the window with all the components we have added to it. Here is our app.js in full...

Titanium.UI.setBackgroundColor('#000');
var window1 = Titanium.UI.createWindow({
})

var button1 = Titanium.UI.createButton({
    title:'Press me'
})
window1.add(button1);

var warninglabel = Titanium.UI.createLabel({
    text:'press the button'
})
window1.add(warninglabel);
window1.open();

When we run this in our emulator the problems become apparent. The button and our label are both placed at the same location  and overlap each other. Our app also does nothing. What we want it to do is have a piece of text saying "press the button" with a button. When we press the button the text will change to "you pressed the button" We now need to clean up our positioning and also make our app work.

If you have ever done any web development you will be familiar with positioning. Everything we pace on a page needs to have a positioning attribute relative to its parent container. To make things nice and simple we will simply place our opjects on our page (in this case window) by specifying a distance from the top.

Lets first of all edit our button. Lets place this pretty close to the top of our window.

var button1 = Titanium.UI.createButtonl({
    top:'10',
    text:'press me'
})

What we have done is specify a distance of 10 pixels from the top of our container, in this case a window.

notice that when ever we have more than one value within our properties section we need to place a ',' between the values as a separator.

We will then place our label below the button...

var warninglabel = Titanium.UI.createLabel({
    top:'80'
    text:'press the button'
})

If we now run the application within our emulator you will notice our layout issues have been resolved.

Android emulator

This image shows our current layout within the Android emulator. as you can see we have placed the items apart simply by using pixel counts from the top of the container. The container could be any parent of the item being placed. It could be a tab, window or view. When ever you are placing a child object you are placing it relative to its position within the parent container. At this stage we have yet to add any functionality to the actual app, but we have improved its layout. 

User interface design is one area where you need to be prepared to learn and apply what you have learned. Positioning of items within Appcelerator Titanium can be simple if you refer to the documentation and follow on from there. There are lots of things you can do to improve positioning of items within a view. The example we are using here is very simple and there are much more effective methods of achieving correct placement of your child objects within a parent. 

Now we have to add an event to the app to give it some functionality. What we want to achieve is changing the text of our label when the user clicks the button. To do this we need to make an event. When ever you add an event to an item, the app will listen for this event being triggered. In this case we want the app to "listen" for a click on our button.

button1.addEventListener('click',function(e) {
warninglabel.text=('You pressed the button')
});  

This code sets up our event. It causes the app to listen for our specified event and carries out an action when the event occurs.

We are going to improve this code to carry out another task. When the user clicks the button there is no need to have it on the window any more. We will in effect hide the button from view once it has been clicked.

button1.addEventListener('click',function(e) {
warninglabel.text=('You pressed the button'),
button1.hide();
});  

If you run the app now you will be able to click the button, the text will change and the button will disappear from display.

App working on Android emulator

This is just a very quick and simple example of how to create a simple Android application using Appcelerator Titanium studio. The same principle could be applied to iPhone and Blackbery if you have the correctly installed SDK's for the different platforms.

In this example what we have is a cross platform application that would run on all of the big three smart phone platforms.

I hope that is quick and dirty example has given you some food for thoght and helped you get your hands dirty with Appcelerator Titanium Studio. I welcome your feedback and look forward to answering any comments or suggestions regarding either this blog post or the Appcelerator Titanium Studio software. I am by no means an Apcelerator expert. I have only been using the toolkit for a couple of weeks but the learning curve is very gradual and the API documentation is very helpful.

I highly recommend you bookmark the Appcelerator Titanium API reference page for future reference. It not only specifies what items are available for use, but it provides you with a breakdown of their individual properties with some useful code examples.

Appcelerator.UI API Documentation

Here is the full source code for the example we just tried out...

Titanium.UI.setBackgroundColor('#000');
var window1 = Titanium.UI.createWindow({
})

var button1 = Titanium.UI.createButton({
    top:'10',
    title:'Press me'
})
window1.add(button1);

button1.addEventListener('click',function(e) {
warninglabel.text=('You pressed the button'),
button.hide();
});

var warninglabel = Titanium.UI.createLabel({
    top:'80',
    text:'press the button'
})
window1.add(warninglabel);
window1.open();

Happy coding.

Mack.