@maccesar/titools 3.3.0 → 4.0.0

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

@@ -0,0 +1,160 @@
+# Alloy Widgets
+
+## Introduction
+
+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 views, controllers, styles and assets and are laid out the same as the `app` directory in the Alloy project.
+
+## Using Widgets
+
+See [Importing Widgets](./VIEWS_XML.md#importing-widgets) for more information on using widgets in your project.
+
+## Creating Widgets
+
+Widgets should be built in their own directory in the Alloy project's `app/widgets/` directory. Widgets have their own views, controllers, models, styles and assets and are laid out the same as the `app` directory in the Alloy project. Also, since widgets are self-contained, they should not reference any code or assets not within its path, except for internationalization and localization files, which are located in the `i18n` folder.
+
+## Assets and Libs
+
+For any files in the `assets` or `libs` folder, use the `WPATH()` macro to automatically map the path relative from the widget's root folder.
+
+For example, if you have a library located at `app/widgets/foo/lib/helper.js`, to require it:
+
+```javascript
+require(WPATH('helper'))
+```
+
+If you have an image located at `app/widgets/foo/assets/images/foo.png`, to reference it:
+
+```javascript
+WPATH('images/foo.png')
+```
+
+## Configuration
+
+Widgets have their own configuration file called `widget.json` located in the widget's root directory.
+
+Example **widget.json**:
+
+```json
+{
+    "id": "com.example.widget",
+    "name": "My Widget",
+    "description": "A sample widget",
+    "author": "Your Name",
+    "version": "1.0",
+    "platform": [
+        "android",
+        "ios"
+    ],
+    "min_alloy": "1.0"
+}
+```
+
+## Controllers
+
+The main controller is called `widget.js` instead of `index.js`.
+
+To use another view-controller besides `widget.js`/`widget.xml`, use the `Widget.createController(controller_name, [params])` method to create a new instance and the `getView()` method to access the Titanium proxy object.
+
+**app/widgets/foo/controllers/widget.js**
+
+```javascript
+const button = Widget.createController('button').getView();
+$.widget.add(button);
+```
+
+All methods in the widget controller are private unless you prefix the method with `$`, which makes it accessible to the Alloy project and other widgets.
+
+**app/widgets/foo/controllers/widget.js**
+
+```javascript
+$.init = args => {
+    $.button.title = args.title || 'Yes';
+    $.button.color = args.color || 'black';
+    const message = args.message || 'Hello World';
+}
+```
+
+Then, in the Alloy project:
+
+```javascript
+$.foo.init({title:'Yes', color:'gray', message:'I pity the foo.'});
+```
+
+## Models
+
+Use models the same way as with a regular Alloy project except to create a model or collection inside a widget controller, use the `Widget.createModel(model_name, [params])` and `Widget.createCollection(model_name, [params])` methods, respectively.
+
+You can also use the `Model` and `Collection` tags in widget views.
+
+## Styles
+
+The main TSS file is called `widget.tss` instead of `index.tss`.
+
+## Themes
+
+Widget themes work the same as project themes except for the placement of the files. Inside your theme folder (`app/themes/<THEME_NAME>`), create `widgets/<WIDGET_NAME>` folders, where `<THEME_NAME>` is the name of the theme and `<WIDGET_NAME>` is the name of the widget. When using a theme, the files in these folders replace the files in the widget's folders.
+
+Create two folders, `assets` and `styles`, to place your custom images and styles for your widget, respectively.
+
+```
+app
+├── themes
+│   └── mytheme
+│       └── widgets
+│           └── mywidget
+│               ├── assets
+│               │   ├── ios
+│               │   │   └── star_half.png
+│               │   ├── star.png
+│               │   └── star_off.png
+│               └── styles
+│                   ├── ios
+│                   │   └── star.tss
+│                   └── star.tss
+└── widgets
+    └── mywidget
+        ├── assets
+        │   ├── star.png
+        │   ├── star_half.png
+        │   └── star_off.png
+        ├── controllers
+        │   ├── star.js
+        │   └── widget.js
+        ├── styles
+        │   ├── star.tss
+        │   └── widget.tss
+        ├── views
+        │   ├── star.xml
+        │   └── widget.xml
+        └── widget.json
+```
+
+To use a theme, in the project's `config.json` file, add the `theme` key with the name of the theme folder as the value.
+
+## Views
+
+The main view is called `widget.xml` instead of `index.xml`.
+
+Specifying the `id` attribute in the XML markup components will make it easier to access and override Titanium object properties. For example, if you have a Button object in a widget view with id `button` and in the Alloy project the widget id is `foo`:
+
+```javascript
+Ti.API.info("button state: " + $.foo.button.enabled);
+```
+
+For widgets that have multiple view-controllers, to include a widget's view-controller in another widget's view, use the `Widget` tag and assign the `name` attribute with the name of the view-controller minus the file extension. Since Alloy 1.5.0, if you omit the `src` attribute, Alloy assumes you are referencing the current widget. For Alloy 1.4.x and prior, you need to assign the `src` attribute to the widget's name.
+
+**app/widgets/foo/views/widget.xml**
+
+```xml
+<Alloy>
+  <View>
+    <Widget src="foo" name="button"/>
+  </View>
+</Alloy>
+```
+
+## Widgets
+
+Widgets can also contain other widgets. Follow the same directions from [Importing Widgets](./VIEWS_XML.md#importing-widgets) except the widget's configuration file is called `widget.json` instead of `config.json`.
+
+To create a widget inside a widget controller, use the `Widget.createWidget(widget_name, [controller_name], [params])` method.

package/skills/alloy-howtos/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: alloy-howtos
+description: Use when an Alloy MVC project needs help with the Alloy CLI (`alloy new`, `alloy generate`, `alloy compile`, `alloy extract-i18n`), configuration files (`alloy.jmk` build hooks, `config.json` env/platform precedence, `widget.json`), conditional views (`if=` attribute in XML/TSS), custom XML tags via `app/lib/`, Backbone.Events for cross-controller communication, or debugging Alloy compilation errors. Triggers include `app/views/` + `app/controllers/`, `alloy.jmk`, or `config.json` in the project root.
+---
+
+# alloy-howtos
+
+## Overview
+
+Practical reference for Titanium Alloy MVC projects: CLI usage, project configuration, conditional rendering, custom XML tags, cross-controller communication, and common compilation/runtime errors. Reference-style — load the relevant file from `references/` for deeper detail.
+
+## When to use
+
+Use this skill when:
+
+- The project contains `app/views/` + `app/controllers/`, `alloy.jmk`, or `config.json`
+- Running or scripting the Alloy CLI (`alloy new`, `alloy generate`, `alloy compile`, ...)
+- Configuring `alloy.jmk` build hooks or `config.json` environment / platform precedence
+- Writing conditional views with `if=` in XML or TSS
+- Building reusable custom XML tags in `app/lib/`
+- Wiring cross-controller communication via `Backbone.Events`
+- Diagnosing Alloy compilation errors or platform-specific runtime issues
+
+Do NOT use for:
+
+- Alloy MVC concepts, controllers, models, or data binding (use `alloy-guides`)
+- Titanium SDK fundamentals, `tiapp.xml`, Hyperloop, or app distribution (use `ti-guides`)
+- Native module dependency updates (use `ti-module-update`)
+
+## Quick reference
+
+| Topic | Reference |
+|---|---|
+| Coding standards, naming, global events patterns | [best_practices.md](references/best_practices.md) |
+| All CLI commands with options and model schema format | [cli_reference.md](references/cli_reference.md) |
+| `alloy.jmk` tasks, `config.json` structure, `widget.json` format | [config_files.md](references/config_files.md) |
+| Creating reusable custom XML tags without widgets | [custom_tags.md](references/custom_tags.md) |
+| Common errors with solutions | [debugging_troubleshooting.md](references/debugging_troubleshooting.md) |
+| Controller examples, conditional views, data-binding patterns | [samples.md](references/samples.md) |
+
+## Key practices
+
+### Naming conventions
+
+- **Never use double underscore prefixes** (`__foo`) — reserved for Alloy
+- **Never use JavaScript reserved words as IDs**
+
+### Global events — use Backbone.Events
+
+Avoid `Ti.App.fireEvent` / `Ti.App.addEventListener`. They cross the native-JS bridge and can cause memory leaks and slower execution.
+
+Use the Backbone.Events pattern:
+
+```javascript
+// In alloy.js
+Alloy.Events = _.clone(Backbone.Events);
+
+// Listener
+Alloy.Events.on('updateMainUI', refreshData);
+
+// Clean up on close
+$.controller.addEventListener('close', () => {
+    Alloy.Events.off('updateMainUI');
+});
+
+// Trigger
+Alloy.Events.trigger('updateMainUI');
+```
+
+### Global variables in non-controller files
+
+Always require Alloy modules:
+
+```javascript
+const Alloy = require('alloy');
+const Backbone = require('alloy/backbone');
+const _ = require('alloy/underscore')._;
+```
+
+## Conditional views
+
+Use `if` attributes in XML for conditional rendering (evaluated before render):
+
+```xml
+<Alloy>
+    <Window>
+        <View if="Alloy.Globals.isLoggedIn()" id="loggedIn">
+            <Label text="Logged in" />
+        </View>
+        <View if="!Alloy.Globals.isLoggedIn()" id="notLoggedIn">
+            <Label text="Not logged in" />
+        </View>
+    </Window>
+</Alloy>
+```
+
+Conditional TSS styles:
+
+```tss
+"#info[if=Alloy.Globals.isIos7Plus]": {
+    font: { textStyle: Ti.UI.TEXT_STYLE_FOOTNOTE }
+}
+```
+
+Data-binding conditionals:
+
+```xml
+<TableViewRow if="$model.shouldShowCommentRow()">
+```
+
+## Common error solutions
+
+| Error | Solution |
+|---|---|
+| `No app.js found` | Run `alloy compile --config platform=<platform>` |
+| Android assets not showing | Use absolute paths (prepend `/`) |
+| `Alloy is not defined` (non-controller) | Add `const Alloy = require('alloy');` |
+| iOS `invalid method passed to UIModule` | Creating Android-only object — use `platform` attribute |
+
+## CLI quick reference
+
+```bash
+# New project
+alloy new [path] [template]
+
+# Generate components
+alloy generate controller <name>
+alloy generate model <name> <adapter> <schema>
+alloy generate style --all
+
+# Compile
+alloy compile [--config platform=android,deploytype=test]
+
+# Extract i18n strings
+alloy extract-i18n en --apply
+
+# Copy / move / remove controllers
+alloy copy <old> <new>
+alloy move <old> <new>
+alloy remove <name>
+```
+
+## Configuration files priority
+
+`config.json` precedence: `os:<platform>` > `env:<environment>` > `global`
+
+Access at runtime: `Alloy.CFG.<key>`
+
+## Custom XML tags
+
+Reusable components without the overhead of widgets. Drop a file in `app/lib/`:
+
+**`app/lib/checkbox.js`**
+```javascript
+exports.createCheckBox = args => {
+    const wrapper = Ti.UI.createView({ layout: 'horizontal', checked: false });
+    const box = Ti.UI.createView({ width: 15, height: 15, borderWidth: 1 });
+    // ... build component, return Ti.UI.* object
+    return wrapper;
+};
+```
+
+**`view.xml`**
+```xml
+<CheckBox module="checkbox" id="terms" caption="I agree" onChange="onCheck" />
+```
+
+The `module` attribute points to the file in `app/lib/` (without `.js`). The function must be `create<TagName>`.
+
+See [custom_tags.md](references/custom_tags.md) for the complete worked example.
+
+## Related skills
+
+| Task | Use this skill |
+|---|---|
+| Alloy MVC concepts, controllers, models, data binding | `alloy-guides` |
+| 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-howtos/references/best_practices.md

@@ -0,0 +1,121 @@
+# Alloy best practices and recommendations
+
+Recommendations for writing Alloy apps. This supplements the Titanium SDK [Best Practices and Recommendations](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/) guide and focuses on coding style and conventions.
+
+## Titanium-to-Alloy Guidance
+
+### Loading Libraries in Alloy
+
+If you need global functionality, require modules in all controllers or create a single global reference:
+
+**alloy.js**
+```javascript
+// Alloy.Globals.refToYourModule will be available in all controllers
+Alloy.Globals.refToYourModule = require('yourModule');
+```
+
+### Performance Best Practices
+
+The same best practices from traditional Titanium development apply to Alloy. Alloy controllers can do what classic controllers can.
+
+Use compiler directives to reduce runtime work (see Conditional Code in Alloy Controllers).
+
+### Project Organization
+
+Decide whether to adapt Alloy to your existing structure, or to adopt Alloy's structure. Alloy standardizes common Titanium patterns and makes projects easier to maintain.
+
+## Coding Style Best Practices
+
+### Naming Conventions
+
+- **Do not use double underscore prefixes** on variables, properties, or function names (e.g., `__foo`). They are reserved for Alloy and may cause conflicts and unexpected behavior.
+- **Do not use JavaScript reserved words as IDs.** See [Titanium SDK Reserved Words](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/Reserved_Words/) for the complete list.
+
+### Global Variables
+
+Avoid declaring globals in app.js and using them in other files. It still works, but it is not recommended and may be deprecated.
+
+Instead, declare these in your JS files:
+
+```javascript
+const Alloy = require('alloy');
+const Backbone = require('alloy/backbone');
+const _ = require('alloy/underscore')._;
+```
+
+Safe pattern for non-controller files:
+
+```javascript
+if (typeof Alloy === 'undefined') {
+    var Alloy = require('alloy');
+}
+if (typeof Backbone === 'undefined') {
+    var Backbone = require('alloy/backbone');
+}
+if (typeof _ === 'undefined') {
+    var _ = require('alloy/underscore')._;
+}
+
+const loading = Alloy.createWidget("com.titaniumsdk.loading");
+```
+
+### Global Events
+
+**Avoid `Ti.App.fireEvent` and `Ti.App.addEventListener`.** It crosses the native-JS bridge and can cause memory leaks and slower execution.
+
+#### Use Callbacks for Master-Child Communication
+
+**master.js**
+```javascript
+function openChild() {
+    Alloy.createController('child', {callback: refreshData});
+}
+
+function refreshData(value) {
+    // Refresh master data here
+}
+```
+
+**child.js**
+```javascript
+const args = arguments[0] || {};
+
+function refreshParent() {
+    // Pass return value to parent
+    args.callback(true);
+}
+```
+
+#### Use Backbone.Events for App-Wide Communication
+
+**alloy.js**
+```javascript
+Alloy.Events = _.clone(Backbone.Events);
+```
+
+**controller_a.js** (listener)
+```javascript
+Alloy.Events.on('updateMainUI', refreshData);
+
+function refreshData(value) {
+    // Do work here
+    // Optionally disable one-time events
+    // Alloy.Events.off('updateMainUI');
+}
+
+// Clean up when closing to avoid memory leaks
+$.controller_a.addEventListener('close', () => {
+    Alloy.Events.off('updateMainUI');
+});
+```
+
+**controller_b.js** (trigger)
+```javascript
+Alloy.Events.trigger('updateMainUI');
+```
+
+**Note:** Alloy controllers are Backbone event dispatchers. You can also use:
+```javascript
+Alloy.createController('child').on('refresh', refreshData);
+```
+This is a simpler way to do cross-controller communication with Backbone events.

package/skills/alloy-howtos/references/cli_reference.md

@@ -0,0 +1,230 @@
+# Alloy command-line interface reference
+
+The Alloy CLI manages and builds Alloy projects.
+
+## Installation
+
+The Alloy CLI is installed when you install the `alloy` package.
+
+### Manual Installation
+
+Install Node.js from [nodejs.org](http://nodejs.org/#download) first, then:
+
+```bash
+sudo npm install -g alloy
+```
+
+For a specific version:
+```bash
+sudo npm install -g alloy@1.10.0
+```
+
+### Development install
+
+```bash
+git clone https://github.com/tidev/alloy.git
+cd alloy
+[sudo] npm install -g .
+```
+
+## Commands
+
+### new
+
+Creates a new Alloy project on top of an existing Titanium project (create the classic Titanium project first, then run this command from inside the project directory).
+
+```bash
+alloy new [<project_path>] [<project_template>] [--force] [--no-colors]
+```
+
+| Option               | Description                                                                       |
+| -------------------- | --------------------------------------------------------------------------------- |
+| `<project_path>`     | Path to skeleton Titanium project (default: current directory)                    |
+| `<project_template>` | **default** (single pane) or **two_tabbed** (tabbed app)                          |
+| `--testapp <path>`   | Relative path to a test application in the Alloy GitHub repo (under `test/apps/`) |
+| `-f, --force`        | Force execution                                                                   |
+| `-n, --no-colors`    | Disable color output                                                              |
+
+### generate
+
+Creates skeleton Alloy components.
+
+```bash
+alloy generate <component> [--widgetname <widget_name>] [--outputPath <output_path>] [--platform <platform>] [--force] [--no-colors]
+```
+
+| Component                         | Description                                                                                                                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `controller <name>`               | Create controller, view and style                                                                                                                                           |
+| `jmk`                             | Create `alloy.jmk`                                                                                                                                                          |
+| `model <name> <adapter> [schema]` | Create model (see Model Format below)                                                                                                                                       |
+| `migration <model_name>`          | Create migration file                                                                                                                                                       |
+| `style <name>` or `--all`         | Create style file (or all styles). If name matches a view-controller, it populates using IDs/classes from markup. Running again updates existing files with new attributes. |
+| `view <name>`                     | Create view and style                                                                                                                                                       |
+| `widget <name>`                   | Create widget                                                                                                                                                               |
+
+| Option                    | Description                                      |
+| ------------------------- | ------------------------------------------------ |
+| `--widgetname <name>`     | Create component for specified widget            |
+| `-o, --outputPath <path>` | Output path (point to 'app' directory)           |
+| `--platform <platform>`   | Create platform-specific component (android/ios) |
+| `-f, --force`             | Force execution                                  |
+| `-n, --no-colors`         | Disable color output                             |
+
+#### Model format
+
+Select adapter type:
+- `sql` - SQLite database for Android/iOS (also generates a migration file)
+- `properties` - Local storage in Titanium SDK context
+
+Schema format: space-delimited list of `field:type`
+- Example: `name:string age:number sex:varchar dob:date`
+
+SQLite type mapping:
+
+| Datatype                                 | SQLite Type |
+| ---------------------------------------- | ----------- |
+| string, varchar, text                    | TEXT        |
+| int, tinyint, smallint, bigint, integer  | INTEGER     |
+| double, float, real                      | REAL        |
+| blob                                     | BLOB        |
+| decimal, number, date, datetime, boolean | NUMERIC     |
+| null                                     | NULL        |
+| unknown                                  | TEXT        |
+
+### install
+
+Installs special Alloy project components.
+
+```bash
+alloy install <module> [<project_path>]
+```
+
+| Module           | Description                               |
+| ---------------- | ----------------------------------------- |
+| `plugin`         | Install compiler plugin for Studio        |
+| `<project_path>` | Project path (default: current directory) |
+
+### compile
+
+Compiles Alloy code to Titanium SDK code.
+
+```bash
+alloy compile [<project_path>] [--config <compiler_options>] [--no-colors]
+```
+
+| Option                   | Description                                                               |
+| ------------------------ | ------------------------------------------------------------------------- |
+| `<project_path>`         | Project path (default: current directory)                                 |
+| `-c, --config <options>` | Comma-delimited compiler options (e.g., `beautify=false,deploytype=test`) |
+| `-n, --no-colors`        | Disable color output                                                      |
+
+Compiler options reference the `event.alloyConfig` object in [Build Configuration File (alloy.jmk)](config_files.md).
+
+### run
+
+Use `titanium build` command to run Alloy projects. See [Titanium Command-Line Interface Reference](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Titanium_Command-Line_Interface_Reference/).
+
+> **💡 Common ti build pitfalls**
+>
+> Using `-C` flag without UDID:
+> ```bash
+> # Prompts for simulator selection interactively
+> ti build -p ios -T simulator -C
+> ```
+>
+> Correct approach for simulator:
+> ```bash
+> # Runs on default simulator
+> ti build -p ios -T simulator
+> ```
+>
+> Using `--no-prompt` incorrectly:
+> ```bash
+> # Still may prompt for device selection if not specific
+> ti build -p ios --no-prompt
+> ```
+>
+> Always specify target:
+> ```bash
+> # Clear target specification
+> ti build -p ios -T simulator --no-prompt
+> ```
+>
+> **Common patterns:**
+> ```bash
+> # iOS Simulator (most common during development)
+> ti build -p ios -T simulator
+>
+> # iOS Device (requires UDID)
+> ti build -p ios -T device -V <udid>
+>
+> # Android Emulator
+> ti build -p android -T emulator
+>
+> # Build only (don't run)
+> ti build -p ios -T simulator --build-only
+> ```
+
+### i18n-extract
+
+Extracts i18n keys from TSS and JS files to strings.xml.
+
+```bash
+alloy extract-i18n [<language>] [--apply]
+```
+
+| Option       | Description                                |
+| ------------ | ------------------------------------------ |
+| `<language>` | Two-letter language code (default: **en**) |
+| `--apply`    | Write to strings.xml (preview if absent)   |
+
+Supported functions:
+- `Ti.Locale.getString()`
+- `L()`
+
+Usage examples:
+```bash
+# Preview changes for default (English)
+alloy extract-i18n
+
+# Write changes to "app/i18n/en/strings.xml"
+alloy extract-i18n --apply
+
+# Specify "es" as the language and write the changes to "app/i18n/es/strings.xml"
+alloy extract-i18n es --apply
+
+# Preview Spanish changes
+alloy extract-i18n es
+```
+
+### copy
+
+Copy a view-controller (controller, XML, TSS).
+
+```bash
+alloy copy <CONTROLLER_NAME> <COPIED_CONTROLLER_NAME>
+```
+
+### move
+
+Rename a view-controller.
+
+```bash
+alloy move <CONTROLLER_NAME> <NEW_CONTROLLER_NAME>
+```
+
+### remove
+
+Remove a view-controller.
+
+```bash
+alloy remove <CONTROLLER_NAME>
+```
+
+## Additional Options
+
+| Option          | Description           |
+| --------------- | --------------------- |
+| `-h, --help`    | Output command usage  |
+| `-v, --version` | Output version number |