Getting started with Titanium

They say that a problem shared is a problem halved, so here at Control F1 we’re all about sharing. In this post, Senior Developer Gabby Littler describes a problem she recently encountered with Titanium, and how she overcame it. We hope it might help others who are using this technology for the first time…

As a developer, I’m sure this situation is familiar to you. You’re starting out on with a new technology, and you need to get something working quickly. It can be difficult to find a route into the documentation and find the sections you need to get something up and working. That’s the situation I was in with Titanium a few months ago, so I’ve put together a simple example of an app with a login screen to help get you started. In this article I’ll go through how I handled the login, how I achieved the layout of the screen, the general approach I took to styling it, and how I added finishing touches to make it feel nice and usable. The full project is available here: https://bitbucket.org/controlf1/alloy-logintutorial. Handling the login The login is handled in the doLogin function. In the example this is just a placeholder, but this is where you would add your code to validate the fields and authenticate the user.

function doLogin(e) {
	// Put your login logic here
	alert("Logging in with user name '" + $.usernameTextField.value + "' and password '" + $.passwordTextField.value + "'");
}

Layout The layout is handled in index.xml, using standard controls. To achieve my layout I used three main principles:

  1. If you don’t specify a layout for a component, it will have an absolute layout.
  2. If a component has an absolute layout, its children will be centred in the view unless you specify otherwise.
  3. If a component has a vertical layout, its children will laid out one after the other, you guessed it, vertically.

Using those rules, you can see how my screen is built up. I have the darkBox view that sits neatly in the centre of the window.

<View id="darkBox" class="darkGreenBg rounded" width="80%" height="50%">

Sitting in the centre of that I have the transparentCentredBox. This has a vertical layout for my login controls. It is styled to be exactly the right size for these controls, so they are nicely centred on my screen as well.

<View id="transparentCentredBox" class="widthFill heightSize vertical">

At the bottom of the screen I have a control (in this case a button that links to our website). This is sitting inside an absolute layout but is anchored to the bottom with bottom=“10”. I didn’t specify a left or right setting, so the control is centred horizontally.

<Button id="linkButton" class="heightSize transparentBg white" title="www.controlf1.co.uk" onClick="openLink" bottom="10"/>

Styling The styling for this example is mostly done in index.tss. I use a variety of different styling techniques here. Specific components To style a specific component, I add an entry to the .tss file for the id of that component. For example, the username text field:

"#usernameTextField": {
	autocorrect: false,
	autocapitalization: Ti.UI.TEXT_AUTOCAPITALIZATION_NONE,
	keyboardType: Ti.UI.KEYBOARD_URL,
	returnKeyType: Ti.UI.RETURNKEY_NEXT
},

Specific types of components

For components that all share a group of comment styling elements, I create a class and add the styling to the .tss file. For example the loginControl class is used to style comment elements of my text fields and my login button.

".loginControl": {
	width: "80%",
	top: "10dp",
	bottom: "10dp"
}

Every instance of a control type If I want to style every instance of a particular type of control, I add an entry for that control in the .tss file. For example, the TextField:

"TextField": {
	height: "40dp",
	bubbleParent: false
}

Granular styling

For styles that could apply to lots of different components, for example size constraints, layouts and colours, I create granular style classes. These can be applied easily in the view, are maintainable and make the view code nice and readable. The darkGreenBg class is an example of this. It is declared in the .tss file:

".darkGreenBg": {
	backgroundColor: "#0D6322"
}

It is applied in the .xml as a class wherever it is needed, for example in my darkBox view:

<View id="darkBox" class="darkGreenBg rounded" width="80%" height="50%">

Ad hoc styling You’ll notice that there I have some ad-hoc styling, such as some widths, heights and positions, directly in the .xml file, for example my darkBox view:

<View id="darkBox" class="darkGreenBg rounded" width="80%" height="50%">

I found in some cases where the styling only applies to a single control it’s much more readable and maintainable to add these styles inline. This is a personal preference, and you may prefer to separate all your styles out into the .tss file. Finishing touches I added a couple of finishing touches that make the form feel a bit more polished. Keyboard type To make inputting values feel natural, I set some properties on the text fields in index.tss. For the user name field I turned off auto-correct and auto-capitalisation. I set the keyboard up to expect URLs so email addresses can easily be entered, and I set the text of the return key to Next (for iOS only).

"#usernameTextField": {
	autocorrect: false,
	autocapitalization: Ti.UI.TEXT_AUTOCAPITALIZATION_NONE,
	keyboardType: Ti.UI.KEYBOARD_URL,
	returnKeyType: Ti.UI.RETURNKEY_NEXT
}

For the password field I set the return key text to Go and I turned on the password mask.

"#passwordTextField": {
	returnKeyType: Ti.UI.RETURNKEY_GO,
	passwordMask: true
}

Handle the keyboard return

By default, returning from the keyboard simply blurs its text field. This would make filling in the form a very stilted experience, so to make it slicker I overrode it. I added the onReturn handlers to the text fields.

<TextField class="loginControl" hintText="User name" id="usernameTextField" onReturn="focusPassword"/>

Returning from the user name field focuses the password field. Returning from the password field calls the login code.

Hide keyboard

Users typically expect the keyboard to be hidden when they click outside of a text field. This is done by adding a click listener to your window.

<Window id="window" class="fill lightGreenBg" onClick="hideKeyboard">

The listener blurs the text fields on the screen, which will hide the keyboard.

function hideKeyboard() {
    $.usernameTextField.blur();
    $.passwordTextField.blur();
}

You also need to remember to set bubbleParent for the text fields to false in index.tss. Otherwise click events on these will bubble up to the window and call hideKeyboard, immediately blurring the field again.

"TextField": {
	height: "40dp",
	bubbleParent: false
}

Summary That concludes my article on how to create a simple login screen with Titanium. I hope you find it useful. Feel free to comment below if you have anything to add.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s