alloy-guides（合金导轨）

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

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: ``tss // WRONG - Adds Ti.UI.iOS to Android project "#mainWindow": { statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT // FAILS on Android! } ` Correct approach - use platform modifiers: `tss // 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: