@maccesar/titools 2.0.0

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

@@ -0,0 +1,253 @@
+# Alloy Command-Line Interface Reference
+
+The Alloy CLI is a command-line tool for managing and building Alloy projects.
+
+## Table of Contents
+
+- [Alloy Command-Line Interface Reference](#alloy-command-line-interface-reference)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+    - [Manual Installation](#manual-installation)
+    - [Bleeding Edge Installation](#bleeding-edge-installation)
+  - [Commands](#commands)
+    - [new](#new)
+    - [generate](#generate)
+      - [Model Format](#model-format)
+    - [install](#install)
+    - [compile](#compile)
+    - [run](#run)
+    - [i18n-extract](#i18n-extract)
+    - [copy](#copy)
+    - [move](#move)
+    - [remove](#remove)
+  - [Additional Options](#additional-options)
+
+---
+
+## Installation
+
+The Alloy CLI is automatically installed when installing 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
+```
+
+### Bleeding Edge Installation
+
+```bash
+git clone https://github.com/tidev/alloy.git
+cd alloy
+[sudo] npm install -g .
+```
+
+## Commands
+
+### new
+
+Creates a new Alloy project on an existing Titanium project.
+
+```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/).
+
+:::tip COMMON ti build PITFALLS
+
+**❌ Using `-C` flag without UDID:**
+```bash
+# WRONG - Prompts for simulator selection interactively
+ti build -p ios -T simulator -C
+```
+
+**✅ Correct approach for simulator:**
+```bash
+# GOOD - 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
+# GOOD - 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 |

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

@@ -0,0 +1,87 @@
+# Alloy Configuration Files Reference
+
+## Table of Contents
+
+- [Alloy Configuration Files Reference](#alloy-configuration-files-reference)
+  - [Table of Contents](#table-of-contents)
+  - [Build Configuration File (alloy.jmk)](#build-configuration-file-alloyjmk)
+    - [Compiler Tasks (Event Names)](#compiler-tasks-event-names)
+    - [Event Object](#event-object)
+    - [Logger Object](#logger-object)
+    - [Objects](#objects)
+    - [Keys](#keys)
+
+---
+
+## Build Configuration File (alloy.jmk)
+
+Alloy provides hooks to customize compilation using a JS Makefile (JMK).
+
+**Location:** `app/alloy.jmk`
+
+**Example:**
+```javascript
+task('pre:compile', (event, logger) => {
+    logger.showTimestamp = true;
+    logger.info(`building project at ${event.dir.project}`);
+});
+
+task('post:compile', (event, logger) => {
+    logger.info('compile finished!');
+});
+```
+
+### Compiler Tasks (Event Names)
+
+| Task             | When Called                                               |
+| ---------------- | --------------------------------------------------------- |
+| `pre:load`       | After project clean, before copying assets to `Resources` |
+| `pre:compile`    | Before compiler starts                                    |
+| `post:compile`   | After compiler finishes, before exit                      |
+| `compile:app.js` | After compiling `app.js`, before writing to disk          |
+
+### Event Object
+
+| Property       | Type    | Description                                                                                                                                                                                                         |
+| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `adapters`     | Array   | List of adapters                                                                                                                                                                                                    |
+| `alloyConfig`  | Object  | Compiler config: `platform` (android/ios), `file` (selective compile), `deploytype` (development/test/production), `beautify` (Boolean)                                                                             |
+| `autoStyle`    | Boolean | Autostyle enabled for project                                                                                                                                                                                       |
+| `dependencies` | Object  | Value of `dependencies` key in config.json                                                                                                                                                                          |
+| `dir`          | Object  | Directory paths: `home` (app path), `project` (root path), `resources`, `resourcesAlloy`, `assets`, `config`, `controllers`, `migrations`, `models`, `styles`, `themes`, `views`, `widgets`, `builtins`, `template` |
+| `sourcemap`    | Boolean | If `true`, generates mapping files to link generated Titanium files in `Resources` back to the source files in `app` for debugging.                                                                                 |
+| `theme`        | String  | Theme name being used                                                                                                                                                                                               |
+| `code`         | String  | *(compile:app.js only)* Contents of `app.js`                                                                                                                                                                        |
+| `appJSFile`    | String  | *(compile:app.js only)* Absolute path to `app.js`                                                                                                                                                                   |
+
+### Logger Object
+...
+### Objects
+
+| Object            | Description                                                 |
+| ----------------- | ----------------------------------------------------------- |
+| `global`          | Key-value pairs for all environments and platforms          |
+| `env:development` | Development builds (simulator/emulator)                     |
+| `env:test`        | Test builds on device                                       |
+| `env:production`  | Production builds (after package installation)              |
+| `os:android`      | Android-specific values                                     |
+| `os:ios`          | iOS-specific values                                         |
+| `dependencies`    | Widget dependencies (name: version)                         |
+| `autoStyle`       | Enable autostyle for entire project                         |
+| `backbone`        | Backbone.js version: `0.9.2` (default), `1.1.2`, or `1.3.3` |
+
+**Precedence:** `os` > `env` > `global`. Combinations (e.g., `os:ios env:production`) override single values.
+...
+### Keys
+
+| Key                    | Type   | Required | Description                           |
+| ---------------------- | ------ | -------- | ------------------------------------- |
+| `id`                   | String | Yes      | Must match widget root folder name    |
+| `copyright`            | String | No       | Copyright information                 |
+| `license`              | String | No       | License information                   |
+| `min-alloy-version`    | Float  | No*      | Minimum Alloy version required        |
+| `min-titanium-version` | Float  | No*      | Minimum Titanium version required     |
+| `tags`                 | String | No       | Comma-delimited keywords              |
+| `platforms`            | String | No*      | Supported platforms (comma-delimited) |
+
+(*) Currently, `min-alloy-version`, `min-titanium-version`, and `platforms` are not strictly enforced, but Alloy will perform checks against these in future versions.

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

@@ -0,0 +1,147 @@
+# Creating Custom Tags in Titanium with Alloy
+
+Custom tags allow you to create reusable UI components without the overhead of widgets. They are an incredibly fast way to build a suite of controls that are as easy to use as dropping a file into the `app/lib` folder.
+
+## Table of Contents
+
+- [Creating Custom Tags in Titanium with Alloy](#creating-custom-tags-in-titanium-with-alloy)
+  - [Table of Contents](#table-of-contents)
+  - [Why Use Custom Tags?](#why-use-custom-tags)
+  - [Basic Setup](#basic-setup)
+  - [Robust Example: CheckBox](#robust-example-checkbox)
+  - [Global Module Override](#global-module-override)
+  - [Key Points](#key-points)
+  - [Custom Tags vs Widgets](#custom-tags-vs-widgets)
+
+---
+
+## Why Use Custom Tags?
+
+When building cross-platform applications, you often need specific UI controls (like a web-style checkbox) that don't exist natively. You have three main approaches:
+
+1.  **Direct XML/JS:** Copy-pasting code into every view. Not reusable and messy.
+2.  **Widgets:** Highly reusable but requires a folder structure and `dependencies` in `config.json`.
+3.  **Custom Tags:** Single file in `app/lib/`, no config dependency, and very simple to share. They reduce the amount of platform-specific code in your views, keeping them simple and readable.
+
+## Basic Setup
+
+1.  Create a file in `app/lib/` (e.g., `checkbox.js`)
+2.  Export a `create<TagName>` function
+3.  Use in XML with the `module` attribute
+
+**view.xml**
+```xml
+<CheckBox module="checkbox" id="termsAccepted"
+    caption="I agree to the terms of use"
+    underline="true"
+    onCaptionClick="doShowTerms"
+    onChange="onCheckChange" />
+```
+The `module` attribute tells Alloy to look in `checkbox.js` for a `createCheckBox` function, pass it the arguments from XML/TSS, and expect a `Ti.UI.*` component back.
+
+## Robust Example: CheckBox
+
+**app/lib/checkbox.js**
+```javascript
+exports.createCheckBox = args => {
+    // Wrapper view for all components
+    const wrapper = Ti.UI.createView({
+        top: args.top || 5,
+        width: Ti.UI.SIZE,
+        height: Ti.UI.SIZE,
+        layout: "horizontal",
+        left: args.left || 20,
+        right: args.right || null,
+        checked: args.checked || false
+    });
+
+    // The box itself
+    const box = Ti.UI.createView({
+        width: 15,
+        height: 15,
+        borderWidth: 1,
+        borderColor: "#02A9F4"
+    });
+
+    // Attributed string for styled caption (e.g. underline)
+    const attr = Ti.UI.createAttributedString({
+        text: args.caption
+    });
+
+    if (args.underline) {
+        attr.applyProperties({
+            attributes: [{
+                type: Ti.UI.ATTRIBUTE_UNDERLINES_STYLE,
+                value: Ti.UI.ATTRIBUTE_UNDERLINE_STYLE_SINGLE,
+                range: [0, args.caption.length]
+            }]
+        });
+    }
+
+    const caption = Ti.UI.createLabel({
+        color: "#000",
+        attributedString: attr,
+        left: 10,
+        text: args.caption,
+        font: { fontSize: 10 }
+    });
+
+    // The tick (using Unicode to avoid assets)
+    const tick = Ti.UI.createLabel({
+        text: "\u2713",
+        left: 1,
+        color: "#02A9F4",
+        font: { fontWeight: "bold" },
+        visible: args.checked || false
+    });
+
+    // Handle clicks
+    caption.addEventListener("click", () => {
+        wrapper.fireEvent("captionClick");
+    });
+
+    box.addEventListener("click", () => {
+        tick.visible = !tick.visible;
+        wrapper.checked = !wrapper.checked;
+        wrapper.fireEvent("change", { checked: wrapper.checked });
+    });
+
+    box.add(tick);
+    wrapper.add(box);
+    wrapper.add(caption);
+
+    return wrapper;
+};
+```
+
+## Global Module Override
+
+Apply a module to all tags in a view by updating the `Alloy` tag. Alloy will check your specified file for any tag creation overrides before falling back to default implementations:
+
+```xml
+<Alloy module="ui">
+    <Window>
+        <CustomButton />  <!-- Looks for createCustomButton in app/lib/ui.js -->
+        <Label />         <!-- Checks ui.js for createLabel first -->
+    </Window>
+</Alloy>
+```
+This is powerful for adding default colors or properties (like a black default color for Android Labels) across an entire project.
+
+## Key Points
+
+| Aspect        | Description                                                   |
+| ------------- | ------------------------------------------------------------- |
+| File location | `app/lib/<module_name>.js`                                    |
+| Function name | `create<TagName>` (e.g., `createCheckBox` for `<CheckBox>`)   |
+| Return value  | Must return a `Ti.UI.*` component (View, Button, Label, etc.) |
+| Arguments     | Receives all XML/TSS attributes in a single `args` object     |
+
+## Custom Tags vs Widgets
+
+| Custom Tags                           | Widgets                                  |
+| ------------------------------------- | ---------------------------------------- |
+| Single file in `app/lib/`             | Separate folder structure                |
+| No `config.json` dependency needed    | Requires `dependencies` in `config.json` |
+| Simpler for single-component controls | Better for complex multi-view components |
+| Easier to share across projects       | More formal packaging                    |

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

@@ -0,0 +1,101 @@
+# Alloy Debugging and Troubleshooting
+
+## Table of Contents
+
+- [Alloy Debugging and Troubleshooting](#alloy-debugging-and-troubleshooting)
+  - [Table of Contents](#table-of-contents)
+  - [Overview](#overview)
+  - [Debugging](#debugging)
+    - [Compiler Error Messages](#compiler-error-messages)
+  - [Troubleshooting](#troubleshooting)
+    - [Error: No app.js Found](#error-no-appjs-found)
+    - [Android: Images, HTML and Assets Not Displaying](#android-images-html-and-assets-not-displaying)
+    - [Android Runtime Error: Cannot Call Method of Undefined](#android-runtime-error-cannot-call-method-of-undefined)
+    - [Android Runtime Error: Alloy is Not Defined](#android-runtime-error-alloy-is-not-defined)
+    - [iOS Application Error: Invalid Method Passed to UIModule](#ios-application-error-invalid-method-passed-to-uimodule)
+    - [iOS Application Error: Undefined is Not an Object](#ios-application-error-undefined-is-not-an-object)
+  - [Getting Help](#getting-help)
+  - [Submitting a Bug Report](#submitting-a-bug-report)
+
+---
+
+## Overview
+
+This guide covers debugging and troubleshooting Alloy applications.
+
+## Debugging
+
+### Compiler Error Messages
+
+The Alloy compiler generates error messages for syntax errors in JavaScript, JSON, TSS and XML files. Error messages report:
+- File path
+- Line and character position
+- Description of the error
+
+## Troubleshooting
+
+### Error: No app.js Found
+
+**Error:** `[ERROR] No app.js found. Ensure the app.js file exists in your project's Resources directory.`
+
+**Solution:** If part of the contents of your `Resources` folder were deleted, run:
+```bash
+alloy compile --config platform=<platform>
+```
+
+### Android: Images, HTML and Assets Not Displaying
+
+**Problem:** Assets display on iOS and Mobile Web but not Android.
+
+**Solution:** Android requires absolute paths. Precede asset paths with a slash ('/'). iOS and Mobile Web accept both relative and absolute paths.
+
+### Android Runtime Error: Cannot Call Method of Undefined
+
+**Error:** `Uncaught TypeError: Cannot call method xxx of undefined`
+
+**Causes:**
+1. Creating an iOS-only Titanium object. Use the `platform` attribute in views to enforce platform-specific objects.
+2. Top-level UI component has an assigned ID. The controller cannot use `$.<controller_name>` to reference it; use the assigned ID instead.
+
+### Android Runtime Error: Alloy is Not Defined
+
+**Error:** `Uncaught ReferenceError: Alloy is not defined`
+
+**Cause:** Non-controller JavaScript files are not automatically wrapped by Alloy.
+
+**Solution:** Require the 'alloy' module:
+```javascript
+const Alloy = require('alloy');
+```
+
+### iOS Application Error: Invalid Method Passed to UIModule
+
+**Error:** `invalid method (xxx) passed to UIModule (unknown file)`
+
+**Cause:** Trying to create an Android-only Titanium object.
+
+**Solution:** Use the `platform` attribute in the view to enforce platform-specific objects.
+
+### iOS Application Error: Undefined is Not an Object
+
+**Error:** `undefined is not an object (evaluating $.xxx.open) (unknown file)`
+
+**Cause:** Top-level UI component has an assigned ID in XML markup.
+
+**Solution:** The controller cannot use `$.<controller_name>` to reference it; use the assigned ID instead.
+
+## Getting Help
+
+Use the [Titanium Community Questions and Answers Forum](https://developer.axway.com/develop-apps#DevelopApps_Engage):
+- Include 'alloy' as a tag
+- Include the Alloy version (run `alloy --version`)
+- Include platform information
+
+## Submitting a Bug Report
+
+Use [GitHub Issues](https://github.com/tidev/alloy/issues):
+- Select 'Alloy' as the component
+- Include Alloy version (`alloy --version`)
+- Include environment information
+
+For detailed instructions, see [How to Report a Bug or Make a Feature Request](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Contributing_to_Titanium/How_to_Report_a_Bug_or_Make_a_Feature_Request/).