@maccesar/titools 2.0.0

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

@@ -0,0 +1,176 @@
+# Alloy Widgets
+
+## Table of Contents
+
+- [Alloy Widgets](#alloy-widgets)
+  - [Table of Contents](#table-of-contents)
+  - [Introduction](#introduction)
+  - [Using Widgets](#using-widgets)
+  - [Creating Widgets](#creating-widgets)
+  - [Assets and Libs](#assets-and-libs)
+  - [Configuration](#configuration)
+  - [Controllers](#controllers)
+  - [Models](#models)
+  - [Styles](#styles)
+  - [Themes](#themes)
+  - [Views](#views)
+  - [Widgets](#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. Additionally, 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.
+
+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.
+
+**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,203 @@
+---
+name: alloy-howtos
+description: "Titanium Alloy CLI and configuration guide. Use when creating, reviewing, analyzing, or examining Alloy projects, running alloy commands (new, generate, compile), configuring alloy.jmk or config.json, debugging compilation errors, creating conditional views, using Backbone.Events for communication, or writing custom XML tags."
+argument-hint: "[task]"
+allowed-tools: Read, Grep, Glob, Edit, Write, Bash(alloy *), Bash(node *)
+---
+
+# Titanium Alloy How-tos
+
+Comprehensive guide for the Alloy MVC Framework in Titanium SDK.
+
+## Project Detection
+
+:::info AUTO-DETECTS ALLOY PROJECTS
+This skill automatically detects Alloy projects when invoked and provides CLI and configuration guidance.
+
+**Detection occurs automatically** - no manual command needed.
+
+**Alloy project indicators:**
+- `app/` folder with Alloy structure
+- `alloy.jmk` or `config.json` files
+
+**Behavior based on detection:**
+- **Alloy detected** → Provides Alloy CLI command guidance, configuration file help, Alloy-specific troubleshooting
+- **Not detected** → Indicates this skill is for Alloy projects only, suggests Alloy guides if user wants to migrate
+:::
+
+## Table of Contents
+
+- [Titanium Alloy How-tos](#titanium-alloy-how-tos)
+  - [Project Detection](#project-detection)
+  - [Table of Contents](#table-of-contents)
+  - [Quick Reference](#quick-reference)
+  - [Critical Best Practices](#critical-best-practices)
+    - [Naming Conventions](#naming-conventions)
+    - [Global Events - Use Backbone.Events](#global-events---use-backboneevents)
+    - [Global Variables in Non-Controller Files](#global-variables-in-non-controller-files)
+  - [Conditional Views](#conditional-views)
+  - [Common Error Solutions](#common-error-solutions)
+  - [CLI Quick Reference](#cli-quick-reference)
+  - [Configuration Files Priority](#configuration-files-priority)
+  - [Custom XML Tags](#custom-xml-tags)
+  - [Resources](#resources)
+    - [references/](#references)
+  - [Related Skills](#related-skills)
+
+---
+
+## Quick Reference
+
+| Topic                                        | Reference                                                               |
+| -------------------------------------------- | ----------------------------------------------------------------------- |
+| Best Practices & Naming Conventions          | [best_practices.md](references/best_practices.md)                       |
+| CLI Commands (new, generate, compile)        | [cli_reference.md](references/cli_reference.md)                         |
+| Configuration Files (alloy.jmk, config.json) | [config_files.md](references/config_files.md)                           |
+| Custom XML Tags & Reusable Components        | [custom_tags.md](references/custom_tags.md)                             |
+| Debugging & Common Errors                    | [debugging_troubleshooting.md](references/debugging_troubleshooting.md) |
+| Code Samples & Conditionals                  | [samples.md](references/samples.md)                                     |
+
+## Critical Best 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` - causes memory leaks and poor performance.
+
+**USE** 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="notLoggedIn">
+             <Label text="Not logged in" />
+        </View>
+        <View if="!Alloy.Globals.isLoggedIn()" id="loggedIn">
+            <Label text="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:ios` > `env:production` > `global`
+
+Access at runtime: `Alloy.CFG.yourKey`
+
+## Custom XML Tags
+
+Create reusable components without widgets - just 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" />
+```
+
+Key: `module` attribute points to file in `app/lib/` (without `.js`), function must be `create<TagName>`.
+
+See [custom_tags.md](references/custom_tags.md) for complete examples.
+
+## Resources
+
+### references/
+
+Complete documentation for each topic area:
+- **best_practices.md** - Coding standards, naming conventions, global events patterns
+- **cli_reference.md** - All CLI commands with options and model schema format
+- **config_files.md** - alloy.jmk tasks, config.json structure, widget.json format
+- **custom_tags.md** - Creating reusable custom XML tags without widgets
+- **debugging_troubleshooting.md** - Common errors with solutions
+- **samples.md** - Controller examples, conditional views, data-binding patterns
+
+## Related Skills
+
+For tasks beyond Alloy CLI and configuration, use these complementary skills:
+
+| Task                                     | Use This Skill |
+| ---------------------------------------- | -------------- |
+| Modern architecture, services, patterns  | `alloy-expert` |
+| Alloy MVC concepts, models, data binding | `alloy-guides` |
+| SDK config, Hyperloop, app distribution  | `ti-guides`    |

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

@@ -0,0 +1,138 @@
+# Alloy Best Practices and Recommendations
+
+This guide provides recommendations for writing Alloy applications. This guide supplements the existing Titanium SDK [Best Practices and Recommendations](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_Guide/Best_Practices_and_Recommendations/) guide, specifically focusing on Coding Best Practices and Style and Conventions.
+
+## Table of Contents
+
+- [Alloy Best Practices and Recommendations](#alloy-best-practices-and-recommendations)
+  - [Table of Contents](#table-of-contents)
+  - [Titanium-to-Alloy Guidance](#titanium-to-alloy-guidance)
+    - [Loading Libraries in Alloy](#loading-libraries-in-alloy)
+    - [Performance Best Practices](#performance-best-practices)
+    - [Project Organization](#project-organization)
+  - [Coding Style Best Practices](#coding-style-best-practices)
+    - [Naming Conventions](#naming-conventions)
+    - [Global Variables](#global-variables)
+    - [Global Events](#global-events)
+      - [Use Callbacks for Master-Child Communication](#use-callbacks-for-master-child-communication)
+      - [Use Backbone.Events for App-Wide Communication](#use-backboneevents-for-app-wide-communication)
+
+---
+
+## Titanium-to-Alloy Guidance
+
+### Loading Libraries in Alloy
+
+If you have pre-existing functionality to make available globally, you can 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. Everything you can do in traditional Titanium development can be done in Alloy's controllers.
+
+Use compiler directives to speed up runtime performance (see Conditional Code in Alloy Controllers).
+
+### Project Organization
+
+Determine if it makes sense to bend Alloy around your existing organization, or bend your existing organization around Alloy. Alloy was created to standardize Titanium coding methodologies, making projects cleaner and more maintainable.
+
+## 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
+
+Do not declare global variables in app.js and use them in other files. This is allowed but not recommended and will 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`** - This crosses the bridge between native and JavaScript lands, which can cause memory leaks and slower processes.
+
+#### 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 cleaner approach to cross-controller communication using Backbone's built-in event capabilities.