@maccesar/titools 3.3.0 → 4.0.0

package/skills/alloy-guides/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: alloy-guides
+description: 'Use when working with Alloy MVC projects: writing or reviewing Alloy controllers (`app/controllers/`), XML views (`app/views/`), TSS styles (`app/styles/`), Backbone models and collections (`app/models/`), sync adapters, migrations, widgets, or the Alloy compilation flow. Triggers include the `app/views/` + `app/controllers/` + `app/styles/` folder structure, or `app/models/` for data work. Alloy XML is not HTML; TSS is not CSS; controllers follow Alloy-specific patterns, not web MVC.'
+---
+
+# alloy-guides
+
+## Overview
+
+Reference for the Alloy MVC framework on top of Titanium SDK. Covers core concepts, controllers, models / collections / data binding, XML markup, TSS styling (static and dynamic), widgets, and the compile pipeline.
+
+## When to use
+
+Use this skill when:
+
+- The project contains `app/views/`, `app/controllers/`, `app/styles/`, or `app/models/`
+- Writing or reviewing Alloy XML markup (`<Alloy>`, `<Window>`, `<View>`, ...)
+- Writing or reviewing TSS styles (static and conditional/dynamic)
+- Defining Backbone models/collections, data binding, or sync adapters
+- Creating, consuming, or packaging widgets
+- Understanding the Alloy compilation pipeline (`alloy.jmk`, code generation)
+- Diagnosing TSS, XML, or model schema issues
+
+Do NOT use for:
+
+- Alloy CLI usage and configuration files (use `alloy-howtos`)
+- Titanium SDK fundamentals, `tiapp.xml`, distribution (use `ti-guides`)
+- Looking up Titanium API surfaces (use `ti-api`)
+- Native module dependency updates (use `ti-module-update`)
+
+## Quick reference
+
+| Topic | Reference |
+|---|---|
+| Core concepts, MVC, Backbone.js, conventions | [CONCEPTS.md](references/CONCEPTS.md) |
+| Controllers, events, conditional code, arguments | [CONTROLLERS.md](references/CONTROLLERS.md) |
+| Models, collections, data binding | [MODELS.md](references/MODELS.md) |
+| Sync adapters, migrations, plain Backbone, Backbone version migration | [MODELS_ADVANCED.md](references/MODELS_ADVANCED.md) |
+| XML markup, elements, attributes, events | [VIEWS_XML.md](references/VIEWS_XML.md) |
+| TSS styling, themes, platform-specific styles | [VIEWS_STYLES.md](references/VIEWS_STYLES.md) |
+| Dynamic styles, autostyle, runtime styling | [VIEWS_DYNAMIC.md](references/VIEWS_DYNAMIC.md) |
+| Controllers-less views, patterns | [VIEWS_WITHOUT_CONTROLLERS.md](references/VIEWS_WITHOUT_CONTROLLERS.md) |
+| Creating and using widgets | [WIDGETS.md](references/WIDGETS.md) |
+| CLI commands, code generation | [CLI_TASKS.md](references/CLI_TASKS.md) |
+| PurgeTSS integration (optional addon) | [PURGETSS.md](references/PURGETSS.md) |
+
+## Project structure
+
+Standard Alloy project layout:
+
+```
+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`)
+```javascript
+function doClick (e) {
+    alert($.label.text);
+}
+$.index.open();
+```
+
+**View** (`app/views/index.xml`)
+```xml
+<Alloy>
+    <Window class="container">
+        <Label id="label" onClick="doClick">Hello, World</Label>
+    </Window>
+</Alloy>
+```
+
+**Style** (`app/styles/index.tss`)
+```javascript
+'.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 their own MVC structure
+- **Conventions** — File naming and placement drive code generation
+
+## Critical rules
+
+### Platform-specific properties in TSS
+
+> **Warning: Platform-specific properties require modifiers**
+>
+> Using `Ti.UI.iOS.*` or `Ti.UI.Android.*` properties in TSS without platform modifiers causes cross-platform compilation failures.
+>
+> ```tss
+> // WRONG — adds Ti.UI.iOS to Android project
+> '#mainWindow': {
+>     statusBarStyle: Ti.UI.iOS.StatusBar.LIGHT_CONTENT  // FAILS on Android
+> }
+>
+> // 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`, anything under `Ti.UI.iOS.*`
+> - **Android:** `actionBar` config, anything under `Ti.UI.Android.*`
+>
+> Available modifiers: `[platform=ios]`, `[platform=android]`, `[formFactor=handheld]`, `[formFactor=tablet]`, `[if=Alloy.Globals.<expression>]`
+>
+> See [VIEWS_DYNAMIC.md](references/VIEWS_DYNAMIC.md) for the full set of conditional / platform modifier patterns.
+
+## Common patterns
+
+### Creating a model
+
+```bash
+alloy generate model book sql title:string author:string
+```
+
+### Data binding
+
+```xml
+<Collection src="book" />
+<TableView dataCollection="book">
+    <TableViewRow title="{title}" />
+</TableView>
+```
+
+### Platform-specific code
+
+```javascript
+if (OS_IOS) {
+    // iOS-only code
+}
+if (OS_ANDROID) {
+    // Android-only code
+}
+```
+
+### Widget usage
+
+```xml
+<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
+
+## Related skills
+
+| Task | Use this skill |
+|---|---|
+| Alloy CLI, `alloy.jmk`, `config.json`, debugging compilation | `alloy-howtos` |
+| Titanium SDK config, Hyperloop, app distribution | `ti-guides` |
+| Titanium API lookup (Ti.UI, Ti.Network, modules) | `ti-api` |
+| Native module dependency updates | `ti-module-update` |

package/skills/alloy-guides/references/CLI_TASKS.md

@@ -0,0 +1,233 @@
+# Alloy Tasks with the CLI
+
+Alloy provides command-line interface (CLI) tasks to create a new project, generate skeleton components such as controllers and models, and compile the source files into the Titanium project.
+
+## Creating a New Application
+
+> **Recommended:** Use `ti create --alloy` to create a new Alloy project in one step.
+
+```bash
+ti create -t app --alloy --id com.example.myapp -n MyApp -p android,ios
+```
+
+This creates a complete Alloy project structure with the `app` folder containing controllers, views, styles, models, and migrations.
+
+**Alternative (interactive):**
+```bash
+ti create
+```
+
+You will be prompted to enter an application name and application ID. When prompted for project type, select **Alloy**.
+
+**Legacy method (not recommended):**
+```bash
+ti create
+cd PROJECTDIRECTORY
+alloy new
+```
+
+This two-step approach is discouraged in favor of using `--alloy` directly.
+
+## Creating a New Application Using a Test Application
+
+You can generate a new Alloy project using a test application from the Alloy Github repo.
+
+```bash
+ti create -t app --classic -i com.appc.picker -n AlloyPicker
+cd AlloyPicker
+alloy new --testapp ui/picker
+```
+
+## Generating Components
+
+The CLI can generate skeleton controllers (with views and styles), models, database migrations and widgets.
+
+### Generating a Controller
+
+To generate a controller with a style and view:
+
+```bash
+alloy generate controller <name> [--widgetname <widget_name>] [-o path_to_project/app] [--platform <platform>]
+```
+
+This creates `app/controllers/<name>.js`, `app/styles/<name>.tss`, and `app/views/<name>.xml`.
+
+### Generating a View
+
+To generate a view and style **without** a controller:
+
+```bash
+alloy generate view <name> [--widgetname <widget_name>] [-o path_to_project/app] [--platform <platform>]
+```
+
+This creates `app/styles/<name>.tss` and `app/views/<name>.xml`.
+
+### Generating a Style
+
+To generate a style for a view-controller:
+
+```bash
+alloy generate style <name> [--widgetname <widget_name>]
+```
+
+Alloy uses the id and attribute names in the markup file to populate the skeleton style file. This creates `app/styles/<name>.tss`. If you add new `id` or `class` attributes to the markup file, running either of these commands updates the style file with the new attributes.
+
+To generate style files for all view-controllers:
+
+```bash
+alloy generate style --all
+```
+
+### Generating a Model
+
+To generate a model:
+
+```bash
+alloy generate model <name> <adapter> [<col_name_1>:<col_type_1> <col_name_2>:<col_type_2> ...] [-o path_to_project/app]
+```
+
+The fourth parameter selects the adapter type: `sql` for SQLite or `properties` for local storage. The fifth parameter defines the table schema. This is required for `sql` and `properties` adapter types.
+
+This creates `app/models/<name>.js`, and `app/migrations/DATETIME_<name>.js` if the adapter type is 'sql'.
+
+### Generating a Migration
+
+To generate a standalone migration for a specific model:
+
+```bash
+alloy generate migration <name> [-o path_to_project/app]
+```
+
+This creates `app/migrations/DATETIME_<name>.js`.
+
+### Generating a Widget
+
+To generate a basic widget:
+
+```bash
+alloy generate widget <name> [-o path_to_project/app]
+```
+
+This creates `app/widgets/<name>/widget.json`, `app/widgets/<name>/controllers/widget.js`, `app/widgets/<name>/styles/widget.tss`, and `app/widgets/<name>/views/widget.xml`. The widget is automatically added to `config.json`.
+
+### Generating alloy.jmk
+
+To generate the build customization file:
+
+```bash
+alloy generate jmk [-o path_to_project/app]
+```
+
+This creates `app/alloy.jmk` with a few task hooks in place.
+
+## Extracting Localization Strings
+
+The `alloy extract-i18n` command inspects your JS, TSS and XML files (since Alloy 1.6.0) for instances of Titanium's localization functions and adds those strings to an i18n strings.xml file.
+
+```bash
+alloy extract-i18n [language] [--apply]
+```
+
+**Parameters**:
+
+* `language` – Optional. Two-letter language code (`en`, `es`, etc.). Default is `en`.
+* `--apply` – Optional. Writes new entries to `strings.xml`. Without it, displays a preview. This is a safe operation: it only adds new entries and never removes existing ones.
+
+Supported functions:
+
+* `Titanium.Locale.getString()`
+* `Ti.Locale.getString()`
+* `L()`
+
+**Example**:
+
+```javascript
+// In JavaScript/TSS
+const name = Ti.Locale.getString('name');
+const color = Titanium.Locale.getString('color');
+const currency = L('currency');
+```
+
+```xml
+<!-- In XML (since Alloy 1.6.0) -->
+<Label textid="greeting" />
+<Button titleid="submit_button" />
+```
+
+**Preview Output** (without --apply):
+
+```
+[INFO] ######## BEFORE ########
+[INFO] <?xml version="1.0" encoding="UTF-8"?>
+[INFO] <resources>
+[INFO] </resources>
+[INFO]
+[INFO] ######## AFTER ########
+[INFO] <?xml version="1.0" encoding="UTF-8"?>
+[INFO] <resources>
+[INFO]     <string name="name">name</string>
+[INFO]     <string name="color">color</string>
+[INFO]     <string name="currency">currency</string>
+[INFO]     <string name="greeting">greeting</string>
+[INFO]     <string name="submit_button">submit_button</string>
+[INFO] </resources>
+```
+
+Running with `--apply`:
+
+```bash
+alloy extract-i18n --apply
+```
+
+Generates `app/i18n/en/strings.xml`.
+
+To generate strings for another language, pass the language code:
+
+```bash
+alloy extract-i18n es --apply
+```
+
+This generates `app/i18n/es/strings.xml`.
+
+```xml
+<resources>
+  <string name="name">name</string>
+  <string name="color">color</string>
+  <string name="currency">currency</string>
+  <string name="greeting">greeting</string>
+  <string name="submit_button">submit_button</string>
+</resources>
+```
+
+## Compiling a Specific View-Controller
+
+To select which Alloy view-controller to compile to Titanium code:
+
+```bash
+alloy compile --config platform=<platform>,file=<file>
+
+## Example
+alloy compile --config platform=android,file=app/controller/index.js
+```
+
+## Building an Application
+
+To build and run an application:
+
+```bash
+ti build --platform <platform> [--project-dir <value>] [--sdk <value>] [<platform_build_options>]
+```
+
+Running this from the root directory of the project compiles the files to the correct location automatically.
+
+## Installing Special Project Components
+
+### Installing the Compiler Plugin
+
+To install the compiler plugin that hooks the Alloy project to Studio:
+
+```bash
+alloy install plugin [path_to_project]
+```
+
+Use this command to update the compiler plugin if your project was created using an older version of Alloy.

package/skills/alloy-guides/references/CONCEPTS.md

@@ -0,0 +1,171 @@
+# 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 uses 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.
+
+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.
+
+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.
+
+Also, Alloy provides built-in support for Underscore.js, which provides a set of utility functions, such as array and iterative helpers.
+
+## 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 SDK to Alloy Mapping
+
+| Titanium SDK Component                                                                  | Alloy Component                                                                                                                                               |
+| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Titanium.UI.\* Objects** (and others: `Ti.Android.Menu`, `Ti.Facebook.LoginButton`, `Ti.Map`, `Ti.Media.VideoPlayer`) | **XML element**. Remove the namespace. For some elements, you may need to assign the `ns` attribute. Some objects are implicitly assigned namespaces by Alloy. |
+| `Titanium.UI.createButton();`                                                           | `<Button />` creates a button                                                                                                                                 |
+|                                                                                         | **TSS element**. Remove the namespace.                                                                                                                        |
+|                                                                                         | `"Button":{ /* Button attributes */ }`                                                                                                                        |
+| **Titanium Object properties**                                                          | **XML attribute** if the property can be expressed as a string, number or Titanium SDK constant.                                                              |
+| `Titanium.UI.createButton({text: "Foobar", top: 0, width: Ti.UI.SIZE});`                | `<Button title="Foobar" top="0" width="Ti.UI.SIZE"/>`                                                                                                         |
+|                                                                                         | **TSS attribute** if the property can be directly expressed as a string, number, Titanium SDK constant, dictionary or array. Indirectly, you can assign a method or value to the `Alloy.Globals` or `Alloy.CFG` namespace and reference it in the TSS file. |
+|                                                                                         | `"Button":{ title: "Foobar", top: 0, width: Ti.UI.SIZE }`                                                                                                     |
+| **Titanium Object properties (proxy)**                                                  | Some properties that take Titanium objects can be expressed inline using XML tags (Property Mapping). See [VIEWS_XML.md](./VIEWS_XML.md#property-mapping).     |
+| **Titanium Object methods**                                                             | Use in the controller code. You need to define the `id` attribute of the object in the XML markup, so the object can be referenced in the controller.         |
+| `const button = Titanium.UI.createButton(); button.setTitle('Push Me!');`               | `// Need to give the object an ID: <Button id="button" />` then `$.button.setTitle('Push Me!');`                                                              |
+| **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. |
+| `const button = Titanium.UI.createButton(); button.addEventListener('click', doClick);` | `<Button onClick="doClick"/>` (doClick needs to be declared in the associated controller)                                                                     |
+
+## 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:
+
+| Directory/File    | Description                                                                                                                                                                                                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `app`             | Contains the models, views, controllers and assets of the application. All work should be done here.                                                                                                                                                                                        |
+| `app/alloy.jmk`   | Build configuration file. See Build Configuration File (alloy.jmk).                                                                                                                                                                                                                         |
+| `app/alloy.js`    | Initializer file used to preconfigure components or override Alloy methods before the main controller is executed.                                                                                                                                                                          |
+| `app/config.json` | Project configuration file. See Project Configuration File (config.json).                                                                                                                                                                                                                   |
+| `app/assets`      | Contains image assets and other files that need to be copied into the `Resources` directory. Reference these files in the code without the 'app/assets' path (and without the platform-specific folder if it is inside one).                                                                 |
+| `app/controllers` | Contains controllers in the format `filename.js` to a corresponding view file `app/views/filename.xml`.                                                                                                                                                                                     |
+| `app/i18n`        | Since Alloy 1.8.0 and Titanium 5.2.0 Language Strings are sourced from `app/i18n` and Alloy will generate the `i18n` folder in the project root.                                                                                                                                            |
+| `app/lib`         | Contains application-specific library code, typically in the CommonJS format.                                                                                                                                                                                                               |
+| `app/migrations`  | Contains database migration files in the format `<DATETIME>_filename.js`. See Migrations for more information.                                                                                                                                                                              |
+| `app/models`      | Contains model files in the format `filename.js`.                                                                                                                                                                                                                                           |
+| `app/platform`    | Since Alloy 1.8.0 platform resources are sourced from `app/platform` and Alloy will generate the `platform` folder in the project root.                                                                                                                                                     |
+| `app/specs`       | Like the `app/lib` folder except it is only used if the deploy type is **not** production (since Alloy 1.2.0).                                                                                                                                                                              |
+| `app/styles`      | Contains view styling in the format `filename.tss`, which is applied to a corresponding view file `app/views/filename.xml`.                                                                                                                                                                 |
+| `app/themes`      | Contains themes to customize the assets and styles of the entire GUI.                                                                                                                                                                                                                       |
+| `app/views`       | Contains views in the format `filename.xml` with the optional corresponding files `app/controllers/filename.js` and `app/styles/filename.tss`.                                                                                                                                              |
+| `app/widgets`     | Contains widget files. Each widget will have its own `app`-like directory structure.                                                                                                                                                                                                        |
+| `i18n`            | Since Alloy 1.8.0 and Titanium 5.2.0 Language Strings are sourced from `app/i18n` and Alloy will generate the `i18n` folder in the project root. Before Alloy 1.8.0, the `i18n` folder was managed in the project root directly.                                                            |
+| `Resources`       | Contains the Titanium files generated by the Alloy interface from the `app` directory. All files will be overwritten each time the application is built. Since Alloy 1.3.0, Alloy creates a separate Titanium project for each platform you build for in the `Resources/<platform>` folder. |
+
+**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 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.
+
+Also, 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.
+
+## 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.
+
+## 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:
+
+```javascript
+const animation = require('alloy/animation');
+$.shake.addEventListener('click', e => {
+  animation.shake($.view);
+});
+```
+
+## 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 it is defined in the build configuration file.