Alloy MVC framework guide Skill

Alloy MVC framework guide

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

Project detection

️ℹ️ 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

| Topic | Reference File | | ------------------------------------------------ | ----------------------------------------------------------------------- | | Core concepts, MVC, Backbone.js, conventions | CONCEPTS.md | | Controllers, events, conditional code, arguments | CONTROLLERS.md | | Models, collections, data binding, migrations | MODELS.md | | XML markup, elements, attributes, events | VIEWS_XML.md | | TSS styling, themes, platform-specific styles | VIEWS_STYLES.md | | Dynamic styles, autostyle, runtime styling | VIEWS_DYNAMIC.md | | Controllers-less views, patterns | VIEWS_WITHOUT_CONTROLLERS.md | | Creating and using widgets | WIDGETS.md | | CLI commands, code generation | CLI_TASKS.md | | PurgeTSS integration (optional addon) | PURGETSS.md |

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

🚨 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

Cleanup: Resources folder cleaned
Build Config: alloy.jmk loaded (pre:load task)
Framework Files: Backbone.js, Underscore.js, sync adapters copied
MVC Generation: Models, widgets, views, controllers compiled to JS
Main App: app.js generated from template
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:

| Task | Use This Skill | | ---------------------------------------------- | -------------- | | Modern architecture, services, patterns | ti-expert | | Alloy CLI, config files, debugging errors | alloy-howtos | | Utility-first styling with PurgeTSS (optional) | purgetss | | Native features (location, push, media) | ti-howtos |

Agent Skills: Alloy MVC framework guide

Install this agent skill to your local

Skill Files