API Development

Getting To Know Alloy (Part One)

3D architecture abstract

This blog post refers to a previous version of Alloy. For updated Alloy reference see the Official Alloy Guides.

The following is the first in a series of introductory posts introducing developers to Alloy, the new MVC framework for Titanium.
A constant request we’ve heard from our developer community, almost since the inception of Titanium, is guidance on architecture and code organization in Titanium apps. As a platform, Titanium provides cross-platform, high-level APIs for animation, UI creation, data access, and the core functionality found in native mobile applications. However, historically, Titanium has not been opinionated in how developers structure their JavaScript applications. This has proved to be positive in the sense that we could focus on surfacing lots of functionality from the underlying platforms, but somewhat negative in that developer (particularly those new to large JavaScript programs) sometimes created application structures that were difficult to maintain and potentially inefficient.
It was decided that Appcelerator needed to provide developers with a predictable project structure, based on established best practices we’ve learned from developing hundreds of Titanium applications. Further, we wanted to provide a framework that could give developers better building blocks for rapidly developing non-trivial applications on top of Titanium, and speed up development overall. The alloy was created to accomplish these goals. To hear more about Alloy from lead framework developer Tony Lukasavage, check out his session at this year’s Codestrong conference:

The team at Appcelerator is really excited about Alloy and the benefits it can provide to our developer community. We’re generating docs, tools in our IDE, and advanced technology to fully integrate Alloy into our platform. However, the “old way” of developing Titanium apps will continue to be supported – we think that maintaining a flexible low-level API is important as well. But for many developers, Alloy represents a new (and improved, IMHO) API for serious Titanium app development. As such, I would like to give our developer community an in-depth look at this new framework over the course of a few posts here on the dev blog.
In this post, we will explore the basic architecture of Alloy, and how Alloy is actually implemented. We will also generate a new Alloy project, and explore what you get “out of the box”. In our next article, we will actually dig in and start writing some code for the seminal TODO-list application demo. NOTE: This tutorial assumes an OS X operating system already configured for Titanium development, but these steps should be pretty easy to reproduce on Windows as well.

Key Architectural Concepts

Alloy is a “component-oriented” application framework that enforces separation of concerns with a Model/View/Controller architecture. Let’s take a look at some of the core architectural concepts for Alloy.

What does “component-oriented” mean?

Alloy applications are designed around reusable components that form the building blocks of your application. A “component” in an Alloy application is a CommonJS module generated from the XML, styles, and JavaScript controller logic written by developers. Most often, these components will be developed specifically for a given application, but Alloy also provides the ability to create reusable components that can be easily shared across applications (called “widgets” by Alloy). Components are responsible for responding to user interaction with UI objects under their control, and for managing and updating their own internal state. Components can be nested within one another, and do not need knowledge of the application’s global state (or at the very least, a very small amount of knowledge of the global state of the app).
Components can be created both in XML markup and programmatically, as we will see in this tutorial series.


The Model/View/Controller (MVC) design pattern is one of the most widely implemented patterns in professional software development. In brief, MVC promotes the separation of data representation, often a graphical user interface (the view), and domain-specific business logic (the model). The “traffic cop” that interacts with data and updates the view is called the controller. Alloy provides facilities for structuring your application code in this way as well.

The Model Tier

The model tier of an application implements business logic, like saving an “order” object or updating an “employee” object in some kind of data store. In Alloy, special JavaScript files contain model logic for persistence using a common interface.

The View Tier

The view tier of an Alloy application is coded with a combination of a Titanium-specific XML dialect and styles provided in Titanium Style Sheets (TSS). XML markup is used to declaratively create a user interface, and define the structure of a component in the application. Since Titanium is a cross-platform development environment, and developers will need to support multiple device types and form factors, we needed to provide an easy mechanism for developers to alter the style and attributes of their components based on platform and screen size. TSS provides a CSS-like mechanism for declaring object properties and styes, optionally customized for different platforms and screen sizes. TSS is a derivative of JSON, so style declarations can contain nested objects, values, and arrays.

The Controller Tier

A JavaScript file is paired with an XML/TSS component declaration to respond to user interaction, handle events, and potentially provide a public interface to work with the internal state of a component. The controller will interact with the model to execute business logic, and update the view of the component as appropriate.

Alloy Project Tour

Now that we understand some of the architectural concepts behind Alloy, let’s dive into an actual Alloy project and explore what’s going on.
Alloy has two primary components – a runtime JavaScript library which is actually executed on the device, and a set of build/compile commands which generate Titanium JavaScript code from declarative markup and TSS styles. Alloy’s compile command is executed before the main Titanium build process is initiated, so much of the “magic” of Alloy happens before your app even makes it onto the device. The Alloy compiler must be installed first before an Alloy app can be created.
Alloy’s compiler and code generators, along with many other build tools at Appcelerator, are now built on node.js – node provides a standard library and CommonJS-based runtime for JavaScript applications outside the browser, and has found widespread use as an option for server-side programming. In this tutorial, we will be working with node, Titanium, and Alloy exclusively from the command line. More information on using Titanium from the command line can be found here.
If you haven’t done so already, download and install node.js. This will set up both the “node” and “npm” commands on your system path. To install the Titanium CLI via npm (the “node package manager”), open a terminal and execute:

sudo npm install -g titanium

To install Alloy, use:

sudo npm install -g alloy

These commands should have now set up “titanium” and “alloy” commands on your system path. Next, generate a new Titanium project, which we will enable as an Alloy app in the next step:

titanium create -d . -n AlloyTest

This will create a new Titanium project in the current working directory. Answer the questions as prompted, and change into the new project folder you just created. Inside this folder, you should find the familiar tiapp.xml and Resources directory typically found in a Titanium application. Just to make sure everything has been created properly, you might try running the generated application on the simulator:

titanium build -p ios -F ipad

To “Alloy enable” this application, we will use the “alloy” command we installed via npm just moments ago:

alloy new .

Listing the contents of the project directory should now reveal some new items:

  • The “app” directory, which is where we will write our JavaScript application code going forward
  • The “plugins” directory, which now contains a ti.alloy compiler plugin
  • A “physical size” native module for Android

Also, you’ll notice Alloy has updated your app’s tiapp.xml file to include the compiler plugin and native module configuration it needs.
The “app” directory contains subfolders for your application code, styles, images, and anything else you’d like to ship with your application. In standard Titanium projects, these types of things would go in the “Resources” directory – with Alloy, the contents of the Resources directory are generated dynamically at compile time. This allows for optimizations such as removing platform-specific code that will not be used.
The subdirectories of the “app” directory organize the constituent elements of your application:

Special Directories

  • The “views” directory contains the structural declarations in XML of your app’s components
  • The “controllers” directory contains the behavior code for your app’s components
  • The “models” directory contains business objects used for persistence and data access.
  • The “styles” directory contains Titanium Style Sheets for your app’s components.
  • The “assets” directory is meant for images and other non-code resources for your application. In practice, the contents of this directory are actually directly copied over to the Resources directory.

Special Files

  • “config.json” at the top-level directory allows developers to specify configuration parameters targeted at either development or production environments.
  • “styles/app.tss” is a global, shared TSS file for your entire application. This is a great place to define default styles for built-in UI controls and shared style classes.

Let’s build and run our project again:

titanium build -p ios

You’ll notice that the default splash screen and app have been replaced with an Alloy-branded splash screen and a simple “Hello World” label. If you inspect the contents of the “Resources” directory, you’ll notice that there’s now a “Resources/alloy” directory, which contains the runtime library for the Alloy framework, and a “Resources/alloy/controllers” directory where Alloy has generated Titanium JavaScript API calls based on the XML and TSS declarations in the “app” directory.

Next time…

In the next installment of this series, we will explore the “view” tier of an Alloy application in depth, and understand how to declaratively (and programmatically) create user interfaces in Alloy.