# Alloy Concepts

# Overview

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.

# Model-View-Controller

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

Backbone.js is a lightweight MVC framework, originally designed for web applications. Alloy models are built on top of Backbone.js, taking advantage of Backbone's rich Model and Collection APIs. You define models using a Javascript file that exports a special JSON object, which uses Backbone's extend functionality to customize models and collections. See Alloy Models for more information on creating model objects and http://backbonejs.org/ (opens new window) for more information on Backbone.js.

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/ (opens new window) 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/android or Resources/iphone folder. For Alloy, the files should be placed in either the app/assets/android or app/assets/iphone folder.

Titanium.UI.createButton();

<!-- Creates a button -->
<Button />

// Does not create a button.  Used to style
// all Button objects in the associated view.
"Button":{
  // Button attributes
}

Titanium.UI.createButton({
  text: "Foobar",
  top: 0,
  width: Ti.UI.SIZE
});

<Button title="Foobar" top="0" width="Ti.UI.SIZE"/>

"Button":{
  title: "Foobar",
  top: 0,
  width: Ti.UI.SIZE
}

var button = Titanium.UI.createButton();
button.setTitle('Push Me!');

// Need to give the object an ID, for example
// <Button id="button" />
$.button.setTitle('Push Me!');

var button = Titanium.UI.createButton();
button.addEventListener('click', doClick);

<!-- doClick needs to be declared
in the associated controller -->
<Button onClick="doClick"/>

# 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/views/index.xml and app/controllers/index.js, then the optional corresponding file app/styles/index.tss. Alloy requires these files to create the initial view-controller Resources/<platform>/alloy/controllers/index.js.

The following is a list of directories and files that can be found in an Alloy project:

Notes: the lib, migrations, themes and widgets folders are not automatically generated when creating a new project. The migrations and widgets folder will be generated by the Alloy command-line interface if any of those components are generated. The lib and themes folders will need to be manually created.

The alloy.jmk file is not automatically generated when creating a new project. Use the command-line interface to generate this file.

# Platform-specific resources

Controllers, views and styles can have platform-specific resources. Just add a folder named android or ios under the component folder and add your platform-specific files for Android or iOS into the folder, respectively.

For example, an iOS-specific view and an Android-specific controller would be look like this:

• app

  • controllers

    • android

      • index.js

    • index.js

  • views

    • ios

      • index.xml

    • index.xml

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 Conditional Code for more details.

Additionally, the 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

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 (opens new window) .

# Builtins

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:

var animation = require('alloy/animation');
$.shake.addEventListener('click', function(e) {
  animation.shake($.view);
});

See Alloy builtins API documentation for the functionality and usage of builtins.

# Compilation process

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.

# Cleanup

The Resources folder is cleaned of any previous built files.

# Build configuration

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 Resources/<platform>/alloy/CFG.js.

The files in the assets and lib folders, as well as the files in the theme's assets folder, are copied to the Resources folder.

The 'pre:compile' task executes at this point if it is defined.

# Model-View-Controller and widget generation

The model files are processed. The compiler creates a JavaScript file per model and copies them to the Resources/<platform>/alloy/models folder.

The widget files are processed. The compiler creates a folder per widget that contains JavaScript files per view-controller and copies them to the Resources/<platform>/alloy/widgets folder.

The style, view, and controller files, as well as the files in the theme's style folder and the app.tss global style file, are processed. The compiler creates a JavaScript file per view-controller and copies them to the Resources/<platform>/alloy/controllers folder.

# Main application

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.

# Code optimization

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.