Alloy MVC framework guide

Reference for building Titanium mobile applications with the Alloy MVC framework and Backbone.js.

Project detection

:::info AUTO-DETECTS ALLOY PROJECTS This skill automatically detects Alloy projects when invoked and provides framework-specific guidance.

Detection occurs automatically - no manual command needed.

Alloy project indicators:

• app/ folder (MVC structure)
• app/views/, app/controllers/ folders
• app/models/ folder

Behavior based on detection:

• Alloy detected → Provides Alloy MVC documentation, Backbone.js patterns, TSS styling, widgets
• Not detected → Indicates this skill is for Alloy projects only, does not suggest Alloy-specific features :::

Quick reference

Project structure

Standard Alloy project structure:

app/
├── alloy.js              # Initializer file
├── alloy.jmk             # Build configuration
├── config.json           # Project configuration
├── assets/               # Images, fonts, files (→ Resources/)
├── controllers/          # Controller files (.js)
├── i18n/                 # Localization strings (→ i18n/)
├── lib/                  # CommonJS modules
├── migrations/           # DB migrations (<DATETIME>_<name>.js)
├── models/               # Model definitions (.js)
├── platform/             # Platform-specific resources (→ platform/)
├── specs/                # Test-only files (dev/test only)
├── styles/               # TSS files (.tss)
├── themes/               # Theme folders
├── views/                # XML markup files (.xml)
└── widgets/              # Widget components

MVC quick start

Controller (app/controllers/index.js):

function doClick(e) {
    alert($.label.text);
}
$.index.open();

View (app/views/index.xml):

<Alloy>
    <Window class="container">
        <Label id="label" onClick="doClick">Hello, World</Label>
    </Window>
</Alloy>

Style (app/styles/index.tss):

".container": { backgroundColor: "white" }
"Label": { color: "#000" }

Key concepts

• Models/Collections: Backbone.js objects with sync adapters (sql, properties)
• Views: XML markup with TSS styling
• Controllers: JavaScript logic with $ reference to view components
• Data Binding: Bind collections to UI components automatically
• Widgets: Reusable components with MVC structure
• Conventions: File naming and placement drive code generation

Critical rules

Platform-specific properties in TSS

:::danger CRITICAL: Platform-specific properties require modifiers Using Ti.UI.iOS.* or Ti.UI.Android.* properties in TSS without platform modifiers causes cross-platform compilation failures.

Example of the failure:

// WRONG - Adds Ti.UI.iOS to Android project
"#mainWindow": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android!
}

Correct approach - use platform modifiers:

// CORRECT - Only adds to iOS
"#mainWindow[platform=ios]": {
  statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT
}

// CORRECT - Only adds to Android
"#mainWindow[platform=android]": {
  actionBar: {
    displayHomeAsUp: true
  }
}

Properties that always require platform modifiers:

• iOS: statusBarStyle, modalStyle, modalTransitionStyle, any Ti.UI.iOS.*
• Android: actionBar config, any Ti.UI.Android.* constant

Available modifiers: [platform=ios], [platform=android], [formFactor=handheld], [formFactor=tablet], [if=Alloy.Globals.customVar]

For more platform-specific patterns, see Code conventions (ti-expert) or Platform UI guides (ti-ui). :::

Common patterns

Creating a model

alloy generate model book sql title:string author:string

Data binding

<Collection src="book" />
<TableView dataCollection="book">
    <TableViewRow title="{title}" />
</TableView>

Platform-specific code

if (OS_IOS) {
    // iOS-only code
}
if (OS_ANDROID) {
    // Android-only code
}

Widget usage

<Widget src="mywidget" id="foo" />

Compilation process

1. Cleanup: Resources folder cleaned
2. Build Config: alloy.jmk loaded (pre:load task)
3. Framework Files: Backbone.js, Underscore.js, sync adapters copied
4. MVC Generation: Models, widgets, views, controllers compiled to JS
5. Main App: app.js generated from template
6. Optimization: UglifyJS optimization, platform-specific code removal

References

Read detailed documentation from the reference files listed above based on your specific task.

Related skills

For tasks beyond Alloy MVC basics, use these complementary skills: