Common Support Questions: Alloy

With last year’s addition of our free Indie Plans for both Titanium and Hyperloop, we’ve seen an influx of new developers join the Appcelerator community. So, we wanted to create a resource for users to troubleshoot their most common development issues and questions.

For the third installment of our series, we take a look at some of the most common support questions for Titanium Alloy. You can also check-out our first two editions, which feature tips for Android and iOS development.

(In this blog, we’ll be linking off to existing posts, articles, and guides and updating it based on comments and suggestions from you, so please leave a comment below.)

Q: How do I create a new Titanium Alloy project in Studio / the CLI?

A: To kick-off building your Titanium application for iPhone or Android, you can create a new Alloy project in Appcelerator Studio or the CLI.

For Studio – open Studio and select File > New > Mobile App Project. Next, select the Default Alloy Project type and continue to the next screen. Once on the Project Location screen, enter the name of your project as well as the name of your personal or organization’s domain. Leave the other fields at their default values. Then click OK, and bam, you’ve opened up a brand new project in Studio.

Find complete instructions on creating a new Titanium Alloy project in Studio here.

Creating a new project in the CLI (Command-Line Interface) is a bit different. The Alloy CLI is a command-line tool for managing and building Alloy projects, and there are a couple of different ways to do this.

Assuming you have XCode, Titanium SDK and Android SDKs installed via Appcelerator Studio (or you’ve installed it separately), you can create a new project from the CLI using:

$ appc new

You’ll be prompted to select the type of app you want to create, so select “Titanium App” then give the project a name – an ID and a project folder is created. Next, you’ll be asked if you want to use Hyperloop (the ability to write JavaScript code to directly access the underlying SDK)  — Y or N to complete the setup and a default Alloy project is ready for you. Now, just change to the project directory and run:

$ appc run

Follow the prompts and the demo project will launch.

Learn additional information about the command-line interface and creating a new Alloy project on top of an existing new Titanium project.

Q: How do I handle platform specific UI elements (like navigation window) and avoid duplication of XML code?

A: One cool feature of Titanium is the ability to redefine Alloy XML tags. By overriding existing Alloy tags (or creating new ones), you can improve cross-platform code by reducing the amount of code you need to write whilst allowing your app to work across different platforms such as iOS and Android.

Typically, much of the Titanium API controls and elements can be shared across platforms like iOS and Android (e.g TabGroup, Windows, Views, Buttons etc). However, in some cases some elements are platform-specific. The NavigationWindow for example is only on iOS, so you would need to include alternative views for Android.

This is where redefining Alloy tags can come in — by creating your own version of say the NavigationWindow tag, you can enable it to work seamlessly on iOS and Android, meaning you only have to write the XML code once, and it’ll work on both platforms!

Check out this quick video or blog post for more tips on how to override existing Alloy tags, create new ones and how to create your own version of the NavigationWindow tag.

Q: What exactly is the meaning of ‘$’ in Alloy, and how can it be leveraged in different ways to access UI elements, add callback methods or clean-up stuff?

A: In Alloy, the $ is a reference to the current controller. Alloy is MVC (Model, View Controller) based so typically each XML view file has an associated controller. If you define a UI element such as a button or label and it has an id attribute, it immediately becomes accessible in the controller using the $ variable, so $.myButton would reference an element with an id=”myButton” in the XML view.

Here’s an example view:

 <label id=”myLabel”>Click the button below</Label>
 <Button onClick=”doClick” >Click me!</Button>

And the accompanying controller file:

function doClick(){

In this example, when the user clicks the button, the onClick event handler will call the “doClick” function in the controller, which is referencing the label by its id (mylabel) and calling the setText method to change the labels text.

Find out more information on how controllers can be used.

Q: What are platform folders, and when should I use them to split code (and more)?

A: One of the really cool features of Alloy is how it can separate code, files and assets by platform, meaning that when you build an app for Android, you *only* get the Android related files packaged into the app.

With Platform folders, you can separate out not only assets like images and documents but also code such as controllers, views and styles. This means that if you had two completely different views for iOS and Android, and it would be difficult or impossible to keep them in one XML file, you can have two separate files both called the same filename. You could have:


with both using the same app/controllers/index.js file. Or you could have the index.js in separate folders too.

Tip: Typically, I try to keep everything in the same files, using conditional code, or separate XML with attributes to separate them, but there are occasions where you have to have separate files, especially where the user interface is significantly different between platforms.

Learn additional details around platform folders and their uses.

Q: What is theming in Titanium Alloy, and why would I use it?

A: Not to be confused with user-selectable themes that work at run-time, Alloy theming works at build-time — so once the app is built, the selected theme is applied. The idea is that you might have the same codebase for multiple clients or apps. With Alloy themes you can have a default, base app, and then use themes to override icons, splash screens, other graphics and styling.

So, for example, if you have an app that’s for a sports team — it shows news, updates, videos, player info, upcoming games etc. Other teams might want to use the same app, but have it branded for them and published separately in the AppStore. With themes you can have multiple branded apps and build them just by changing the theme in Alloy. You can even theme the Tiapp.xml file and others using add-on tools like TiTh. Using this and some simple build scripts, it’s possible to build many different branded versions of an app on multiple platforms from one codebase.

Check out more information on theming in Titanium Alloy.

Q: How do I use Models and Collections in Alloy?

A: Alloy comes packaged with backbone.js, a library that provides an event-based data structure that can be used access models and collections. By implementing backbone, Alloy is able to take advantage of the Backbone.js built-in event model, and bind visual elements to data via collections and models for you, reducing the amount of code you have to write.

A model is an object that contains data – e.g. a user record or contact or local business listing. A Collection is a list of models, so you may have a “businesses” collection which contains a list of “business” models.
Each model will have some attributes like id, name, location, address, telephone number etc.

Collections and Models can easily be bound to views in Alloy, using very little JavaScript code. You can create models and collections using Alloy’s model definitions, or create on-the-fly models and collections with Backbone.js from an array of data.

You can bind collections directly to tables or listviews as easily as adding an attribute to the table or listview called datacollection. After that you would add into your code some attribute placeholders and then call one line of JavaScript to fetch the data and Alloy will bind the collection to the table instantly.

Even better – if you update a model in the collection by say, changing its name, it’ll automatically update in the view without you having to do anything. Where you might have typically had to write a load of code in a “classic” TItanium application to render and refresh the data, Backbone and Alloy data binding does it all for you!

You can find out more about Alloy in the API documentation, and dive even deeper into data binding with Alloy by checking out part one and part two of our Backbone.js blog post series. You can also download our mocx library. If you have other Alloy questions, please leave a comment and we may update this post or create a new one!


Comments are closed.