Seven days with Titanium – day 2 – tables and pickers

Welcome to day 2 with Titanium – Tables and pickers. A short reminder of what we’ve done till now:

Believe it or not, the table is the most used UI element in the iPhone SDK. If you play a little with the applications that come with your “iDevice” you will see that almost all the native apps have tables. Sometimes they are so well designed and the appearance so changed that you don’t even think of them as tables. But in time, while you will learn more, you will be able to spot it and a lot of ideas will come to you :). Also I think that that the pickers are some sort of “undercover tables” so that’s why I’ll present both in the same tutorial.

The Table element

The table element is created using Titanium.UI.createTableView function. This function accepts an object as argument like we are used to – with the different settings we might want to give to the table. Besides the usual properties ( like top, left, etc) we have a very important one named data.

The Data property

The data property will hold the rows of the table as an array. The below code will show you what I’m talking about:

 
var win1 = Titanium.UI.createWindow({
	backgroundColor:"#fff"
});
 
var table1 =  Titanium.UI.createTableView({
	data:[
		{title:"Row 1 - simple row"},
		{title:"Row 2 -  with child", hasChild:true},
		{title:"Row 3 -  with detail", hasDetail:true},
		{title:"Row 4 -  with check", hasCheck:true},
		{title:"Row 5 -  red background", backgroundColor:"#f00"}
	]	
});
 
win1.add(table1);
win1.open();

So, what are we doing here?

We create a window. As we said in day 1, the application needs to have at least one window. Into this window we add table1 with the rows set as above.

This is the simplest way to do it, with the properties of the rows set as the Titanium.UI.TableViewRows documentation page specifies.

If you develop cross-platform you’ll need to take in account that each platform will show the data in it’s way (and some specific things may be missing). Below are 2 screenshots on how the above code looks on iPhone and Android.

Simple table with Titanium on iPhoneSimple table with Titanium on Android

A very important thing to know about tables

The rows into tables are rendered “on request”, so let’s say you have 20 rows – it’s clear that visible will be only a few (10 on a standard height). To save memory and to speed up the application the other rows will be rendered when the user scrolls the table. To do this faster the OS of the device creates some sort of template for each layout of the rows and reuse it changing only what’s different. To take advantage of this you MUST set a className attribute for the rows that share the same layout ( I didn’t do it above to simplify the code).

It is important mainly because for a few rows the memory usage is not too high, but for many rows – depending on how many and what’s inside the row – the app will move slow or even crash. The className can be any string you like:

{title:"Row 1 - simple row", className:"layout_one"}

More about tables

Each table has at least one section and each table can be plain (as above) or grouped. Let’s create a grouped table:

 
var table1 =  Titanium.UI.createTableView({
	style:Titanium.UI.iPhone.TableViewStyle.GROUPED
});
 
var section1 = Titanium.UI.createTableViewSection();
section1.headerTitle = "Hello";
var row1 = Titanium.UI.createTableViewRow({title:"Hello 1"});
var row2 = Titanium.UI.createTableViewRow({title:"Hello 2"});
section1.add(row1);
section1.add(row2);
 
var section2 = Titanium.UI.createTableViewSection();
section2.headerTitle = "Hello2";
var row3 = Titanium.UI.createTableViewRow({title:"Hello 3"});
var row4 = Titanium.UI.createTableViewRow({title:"Hello 4"});
section2.add(row3);
section2.add(row4);
 
table1.setData([section1,section2]);

And the result

Grouped table with Titanium on IphoneGrouped table with Titanium on Android

As you see I used the method setData() to set the content of the table after it is created.

This method accepts any array of sections created with Titanium.UI.createTableViewSection , rows created with Titanium.UI.createTableViewRow or objects that describe the rows as in the first example.

Custom tables

All the above examples show you how to create simple tables. If you want to create a more complicated layout you will need to create custom rows for this and The Custom Rows tutorial explains how to do it..

The Pickers or PickerViews

The pickers are the equivalent of the select tag in html. The only difference is that you can create a multicolumn picker (which in HTML it’s not possible without using some tricks). The function that creates a picker is Titanium.UI.createPicker

A simple picker it’s created with the following code:

var picker = Titanium.UI.createPicker();
var data = [];
data.push(Titanium.UI.createPickerRow({title:'Bananas'}));
data.push(Titanium.UI.createPickerRow({title:'Strawberries'}));
data.push(Titanium.UI.createPickerRow({title:'Mangos'}));
data.push(Titanium.UI.createPickerRow({title:'Grapes'}));
picker.add(data);

Sadly for now it is implemented only on the Apple platform (please correct me if I’m wrong) so here it is how it should look like:
Picker with Titanium

The type property of the picker lets you chose form the next predefined types but you always can create your own multicolumn picker.

Titanium.UI.PICKER_TYPE_PLAIN (default),
Titanium.UI.PICKER_TYPE_DATE_AND_TIME,
Titanium.UI.PICKER_TYPE_DATE,
Titanium.UI.PICKER_TYPE_TIME or
Titanium.UI.PICKER_TYPE_COUNT_DOWN_TIMER.

var picker = Titanium.UI.createPicker({
type:Titanium.UI.PICKER_TYPE_DATE_AND_TIME
});

Date and time picker

Since the tables and the rows are similar you will be able to create your custom rows in the same way as for the tables using of course the specific functions for the picker (linked at the end of the tutorial).

I won’t go further as the post is big enough already but I’ll try in the future to create a set of posts that will be specific to an UI element and where I’ll try to “dissect” it as much as possible.

More resources

Here are some links to follow for more information:

As always, thank you for reading this and I’m waiting for your questions and suggestions. If you have your own tutorials or links I’ll be glad to add them here to improve the quality of the posts.

See you on day 3.

Check the Spanish version of this post:
Siete días con Titanium – día 2 – tablas y selectores

Seven days with Titanium – day 1 – windows, views, navigation and tabs

Today is going to be the first day of the Titanium tutorial for beginners and a pretty long post.
Before we begin here is the recap of what we have written until now (and updated what will come): Seven days with Titanium – day 0 – introduction

As specified in the Introduction post I will try in this lesson to say some things about navigation, windows, views and tabs – the basics of the interface.

I will try to first to enumerate each of these elements and then explain what they do and how to use them. Also each interface element has a link to it’s documentation page on Appcelerator site.

Everything that is related to the interface you will find it into the Titanium.UI module. There are also some platform specific modules that cover elements of interface present only on the specific platform: Titanium.UI.Android,Titanium.UI.iPhone,Titanium.UI.iPad but for now we won’t talk about them.

The Window element

The basic element in a Titanium application is a Window. There is nothing complicated here, it’s a “container” for all the other elements if you wish. An application can have one or more windows but it must to have at least one window. A Window it’s one of the few elements that can exist by itself without the need to be a child of something.

The View element

Another basic element it’s a View. The View can be the analog of a div tag in HTML so basically it’s just a rectangle that can hold other elements for an easy and convenient control of the application’s layout. A View cannot exists by itself it will have to be a child of a Window or other element that accepts Views as child (a TableRowView or another View for example).

The TabGroup and the Tabs

The main navigational elements (and common to all platforms) is the TabGroup and the Tabs. Exactly what the names says – analog with a browser with tabs capabilities , a TabGroup will hold more Tabs. Each Tab will control (open) a window. If you decide that you application will have a TabGroup this will be the “root” of the application. What does it mean? That any window opened by the Tabs in TabGroup will be controlled by this and the TabGroup has one instance only and it cannot be closed or removed, but only hidden.

There is also an iPhone specific navigation element, named NavigationGroup that allows to navigate through windows without the need to create the navigation toolbar/buttons by ourselves.

Example

This is how an application with a TabGroup, 2 Windows, 2 Tabs and a View looks loke on the Android and the iPhone platforms.

Seven days with Titanium- day 1 - androidSeven days with Titanium- day 1 - iPhone

More details about each element

Before we continue it would be great to take a look at each element documentation page because there is a lot of valuable info there. As you see, each interface element has some properties that are setters and/or getters like top, backgroundColor, etc), some methods (add(), open()) and events – usually user interaction events (touchstart, doubletap, etc) or specific events (open,close). Very similar with the web elements.

I want to specify some things:
sizes are in pixels but without the usual “px” notation, or in percents – but this requires to be written as a string:

...
top:25,
width:"50%"
...

colors are in hexa rgb , the short or the long form , don’t use names:

...
backgroundColor:"#f00",
borderColor:"#ff0055"
...

Let’s try to elaborate a little.

The Window element, again

The window element is created using the function Titanium.UI.createWindow.

var win1 = Titanium.UI.createWindow({  
    title:'Tab 1',
    backgroundColor:'#fff'
});

What the above code means? That we pass to the createWindow function an object argument with all the properties that we want to set.

This could be written like this:

var win1 = Titanium.UI.createWindow();
 
win1.title='Tab 1'
win1.backgroundColor='#fff';

I think it’s pretty clear so I won’t go further with the code for view, tabs and so on. It’s similar to this only that you use Titanium.UI.createView, etc

How the tabGroup, tabs and the windows are related

The logic behind the above UI elements it’s as it follows:

The tabGroup is the root of the application, the “master”, it cannot be included in any other UI element.
This holds the tabs( at least one) and a tab, when clicked, opens the window associated with it.

Here is a sample code:

 
// create tab group
var tabGroup = Titanium.UI.createTabGroup();
 
// create base UI tabs and  windows
 
var win1 = Titanium.UI.createWindow({  
    title:'Tab 1',
    backgroundColor:'#fff'
});
var tab1 = Titanium.UI.createTab({  
    icon:'KS_nav_views.png',
    title:'Tab 1',
    window:win1
});
 
var win2 = Titanium.UI.createWindow({  
    title:'Tab 2',
    backgroundColor:'#fff'
});
var tab2 = Titanium.UI.createTab({  
    icon:'KS_nav_views.png',
    title:'Tab 2',
    window:win2
});
 
//  add tab
 
tabGroup.addTab(tab1);  
tabGroup.addTab(tab2);  
// open tab group
tabGroup.open();

The above code will generate a similar interface with the screenshots without the labels “I am window 1” etc and the red view. This would be a good exercise for you :).

Important !

As you see we set the same titles to tab1 – win1 and to tab2 – win2. This is not mandatory from the code point of view. The window associated to each tab is specified using the window property that points to the previous declared window. Why it’s like this then? It’s about usability. The user needs to have the same values when he/she has to associate two visual elements or will get confused. Also Apple might not like this when you will submit your app.

Resources

The above code it’s found in the default app.js file that you get when you create a new project. I only explained a little how things are.

A very very good resource it’s the KitcheSink project form Appcelerator team, found here.

For the advanced coders this is another tutorial on how to create a tooltip with Titanium that basically it’s just a view with a background image.

I think it’s enough for day 1, the post is too long and I’ll only add that I’m waiting for your questions, suggestions and critics if I made any mistake 🙂 With your questions/suggestions I’ll update the post or create a new one linked to “day 1”.

Check the Spanish version of this post:
Siete días con Titanium – Día 1 – Ventanas, vistas, navegación y pestañas

Seven days with Titanium – day 0 – introduction

What is all about?

I intend this to be a set of seven tutorials to help beginners understand how to work with the Titanium mobile framework.

The guys at Appcelerator did a great job with the framework allowing to us, the web developers, to have access on native applications for mobile devices ( Apple iDevices, Android and soon BlackBerry).

The framework reached the 1.4 version and each day more developers seem to be interested in using it – especially because it’s free. The community is great and you’ll find answers on almost any problem you might have. But for the beginners is still a little difficult to start. From here surged the idea of this set of tutorials in which I will try to cover the basics of the development process for iPhone and Android.
Titanium Appcelerator

Some things to start

Each post will contain a header with the previous tutorials written, for an easy follow. It will also have a footer part where some links of interest will be published.

It won’t be daily posts, I will write when I’ll have enough time to test and write the examples. I prefer a better written post to a fast one. And each post might be updated to add forgotten things (or to fix issues) so don’t forget to bookmark it.

The provided code will be licensed under the MIT license so you will be able to use it as you wish.

What should I know and/or what do I need?

Basically you need only Javascript knowledge. Some OOP coding routine would be great but is not mandatory ( we learn on the fly 🙂 .

    To develop for Android you will need Android SDK( Linux / OsX / Windows )
  • To develop for iPhone you will need a Mac ( Apple’s rules not mine)

I will not show you how to install any of the frameworks, SDKs, etc. There are good tutorials and HowTo’s that will show you this so I don’t want to repeat what’s already out there.

What do I need to forget?

May look strange but you really have to forget about something: DOM. Why? Because there is no DOM in there. We are not anymore in the HTML world. So nothing from HTML applies here. There are similar things (events for example) but everything it’s just an analogy to make it easier to use it.

Forget also about using a library ( yes, no MooTools, jQuery, etc…), or at least for a start. Again why? Because all these libraries are DOM oriented and are used to fight with multiple browsers, to please each of them and this adds bloatware to your code – code that will not be used by the devices anyway.

Why “at least for a start” ? Well, later you might miss some functions and methods these libraries have (let’s say the array methods like filter, each, unique, etc… ) but you will be able to implement this by your own and avoid a 150k library.

What you will NOT learn in these tutorials:

You won’t learn Javascript (you need to know it already). You will not learn ObjC and/or Java (in the end this is the purpose of Titanium). I will try to provide the code for each thing you will learn about as well as screenshots and maybe videos.

And at last

What will you learn:

Day 1:

Some things about navigation, windows, views and tabs – the basics of the interface. I will try to briefly explain what does each of these elements and how to use them.

Day 2:

Tables and pickers (or option pickers, the ‘select’ tag equivalent)

Day 3:

Ajax (actually XHR) – on how to use the HttpClient for webpages, XML, JSON and YQL; The webview – how to embed html code in your apps.

Day 4:

Media – images, movies and sounds

Day 5:

GPS and maps.

Day 6:

Some eye-candy with animations and transforms

Day 7:

About orientation and accelerometer.

Day 8:

This will be a post-tutorials day where I’ll sum up the lessons, add links and so on.

I know I said seven days and in the end are 9, but this one and the last do not count as “learning” days. There is a lot of stuff left out like scrollviews, sliders, some modules – Facebook? – more advanced techniques – like app events – but hopefully these will be the subject of another tutorials.

Let me know your thoughts, if you have ideas of what should I write about – remember that this is a beginner’s guide – or to ask questions.

See you in day 1.

Update:

PDF documents on how to install Titanium on each of the supported platforms ( Linux / OsX / Windows ) can be found on Titanium Appcelerator blog, go get them 🙂

Check the Spanish version of this post:
Siete días con Titanium – Día 0 – Introducción