This guide covers the important concepts related to the Alloy framework, including the model-view-controller framework, convention-over-configuration design, widgets, and built-in support from Backbone.js and Underscore.js.
Alloy utilizes the model-view-controller (MVC) pattern, which separates the application into three different components:
- Models provide the business logic, containing the rules, data and state of the application.
- Views provide the GUI components to the user, either presenting data or allowing the user to interact with the model data.
- Controllers provide the glue between the model and view components in the form of application logic.
For example, in a calendar application, the models include events, reminders, invitations and contacts. The views present the calendar data and reminders to the user or allow the user to add events. For reminders, the controller checks the model data and launches a 'reminder' view to the user. For adding events, the controller opens an 'add event' view, then adds the event into the model data once the user entered the data.
An advantage of MVC is the ability to reuse code by separating the functionality. For example, you can have specific views for different devices, while keeping the controller code relatively the same and the model data unchanged.
Alloy: MVC with Backbone
Alloy views are built from Titanium UI components. You define views using XML markup and style them using Alloy Titanium Style Sheets (.tss), which abstracts the creation of these components without using Titanium API calls. Alloy generates the code to create your views. See Alloy Views for more information on creating views.
Alloy controllers generally have a one-to-one relationship with Alloy views. Controllers directly use the Titanium SDK API without an abstraction layer. The controller has access to all of the view components. See Alloy Controllers for more information on creating controllers.
Additionally, Alloy provides built-in support for Underscore.js, which provides a set of utility functions, such as array and iterative helpers. Refer to http://underscorejs.org/ for more information.
Alloy and the Titanium SDK
Alloy uses Titanium SDK to abstracts the creation of UI components through the use of XML markup and style sheets. If Alloy has not implemented a feature of the Titanium SDK or if the feature is not UI related, you can always use the Titanium SDK API in the Alloy controller code or create a CommonJS module to implement a feature. The table below lists what Alloy directly abstracts from the Titanium SDK.
For assets, such as images, any references to the
Resources folder in the Titanium SDK documentation should be replaced with the
app/assets folder to use it for Alloy. For example, the Icons and Splash Screens guide tells you to place files in either the
Resources/iphone folder. For Alloy, the files should be placed in either the
|Titanium SDK Component||Alloy Component|
Titanium Object properties
Titanium Object methods
Use in the controller code. You need to define the
Titanium Object events
XML attribute to bind a callback in the associated controller. Capitalize the first character of the event name and append 'on' to the beginning of the name.
Convention over Configuration
To simplify development, Alloy uses a directory structure and naming conventions to organize the application rather than configuration files. Alloy expects to find files in specific locations. Any folder or file not adhering to the below naming conventions is ignored by Alloy. For example, at generation time, Alloy will look for the mandatory files
app/controllers/index.js, then the optional corresponding file
app/styles/index.tss. Alloy requires these files to create the initial view-controller
The following is a list of directories and files that can be found in an Alloy project:
Contains the models, views, controllers and assets of the application. All work should be done here. See folder descriptions below.
Build configuration file.
Initializer file used to preconfigure components or override Alloy methods before the main controller is executed.
Project configuration file.
Contains image assets and other files that need to be copied into the
Contains controllers in the format
|Since Alloy 1.8.0 and Titanium 5.2.0 Language Strings are sourced from |
Contains application-specific library code, typically in the CommonJS format.
Contains database migration files in the format
Contains model files in the format
|Since Alloy 1.8.0 platform resources are sourced from |
|Like the |
See Library Code for more information.
Contains view styling in the format
Contains themes to customize the assets and styles of the entire GUI.
Contains views in the format
Contains widget files. Each widget will have its own
Since Alloy 1.8.0 and Titanium 5.2.0 Language Strings are sourced from
Contains the Titanium files generated by the Alloy interface from the
widgets folders are not automatically generated when creating a new project. The
widgets folder will be generated by the Alloy command-line interface if any of those components are generated. The
themes folders will need to be manually created.
alloy.jmk file is not automatically generated when creating a new project. Use the command-line interface to generate this file.
Controllers, views and styles can have platform-specific resources. Just add a folder named
windows under the component folder and add your platform-specific files for Android, iOS, Mobile Web or Windows Phone into the folder, respectively.
For example, an iOS-specific view and an Android-specific controller would be look like this:
Alternatively, you can use special conditional code and attributes inside the controllers, views and styles to apply platform-specific code and components. Refer to Controller Conditional Code and View Conditional Code for more details.
assets folder is laid out the same way as the 'Resources' folder in a Titanium project for platform-specific files and density-specific images. Refer to Platform-Specific Resources for more information.
Widgets are self-contained components that can be easily dropped into Alloy-powered Titanium projects. They were conceived as a way to reuse code in multiple applications or to be used multiple times in the same application. Widgets have their own models, views, controllers, styles and assets and are laid out the same as the
app directory in the Alloy project.
- For information on using widgets in a project, see Importing Widgets.
- For information on creating widgets, see Creating Widgets.
- To search publicly available widgets, visit gitTio .
Alloy comes with additional utilities used to simplify certain functions, such as animations, string manipulation, and display unit conversion. These utilities are referred to as 'builtins.' To use these utilities, the controller needs to call
require with 'alloy' as the root directory. For example, to use an animation function to shake the current view by pressing the 'shake' button, add this code to a controller:
See Alloy builtins API documentation for the functionality and usage of builtins.
This section provides a brief overview of how the Alloy command-line interface converts the files in the
app folder to a Titanium project in the
Resources/<platform> folder for each platform you build your project for. Before Alloy 1.3.0, Alloy creates only one Titanium project in the
Resources folder is cleaned of any previous built files.
If the build configuration file,
alloy.jmk, exists, it is loaded. The 'pre:load' task executes at this point if it is defined.
Alloy Framework, Assets and Lib
Alloy framework files, which include the Backbone.js and Underscore.js libraries, sync adapters and base controller class, are copied to the
Resources/<platform>/alloy folder. The Alloy base library,
alloy.js, is copied to the
Resources folder. These files are necessary to run any Alloy project.
The project configuration file,
config.json, is processed and copied to
The files in the
lib folders, as well as the files in the theme's assets folder, are copied to the
The 'pre:compile' task executes at this point if it is defined.
Model-View-Controller and Widget Generation
The style, view and controller files, as well as the files in the theme's style folder and the
Alloy creates a skeleton
app.js file from a template. The contents of this file require some Alloy modules and calls the main view-controller
index.js. If an initializer file,
alloy.js, exists, the entire contents of the file are copied into the
app.js file right before the call to initiate the main view-controller.
Before the file is written to the
Resources directory, the 'compile:app.js' task executes if one is defined in the build configuration file.
The generated code is processed through UglifyJS to optimize the code for speed and compactness. The code is optionally beautified.
If the code is compiled for a specific platform, all conditional code that should not be executed for that platform is removed. For example, if the application contains code sections specifically for iOS but the application is compiled for an Android platform, all of the iOS conditional code is removed.
Required Alloy builtin libraries are copied to the
Resources/<platform>/alloy folder and optimized in the same process as described before.
Then, the 'post:compile' task executes if one is defined in the build configuration file.