@maccesar/titools 5.3.0 → 5.4.0

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

@@ -1,160 +1,82 @@
-# Alloy Widgets
+# Alloy widgets
 
-## Introduction
+A widget packages views, styles, controllers, assets and a manifest for reuse between apps. Use `<Require>` to reuse part of one app; use a widget for a component shared across apps.
 
-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.
+## Create and declare
 
-## 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'))
+```bash
+alloy generate widget com.example.rating
 ```
 
-If you have an image located at `app/widgets/foo/assets/images/foo.png`, to reference it:
+The default controller is named `widget`, with these files under `app/widgets/com.example.rating/`:
 
-```javascript
-WPATH('images/foo.png')
+```text
+controllers/widget.js
+views/widget.xml
+styles/widget.tss
+assets/
+widget.json
 ```
 
-## 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"
+    "id": "com.example.rating",
+    "name": "rating",
+    "version": "1.0.0",
+    "platforms": "android,ios"
 }
 ```
 
-## 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.
+The reverse-DNS ID must be unique across the app's widgets. Declare it in `app/config.json`, including when copying its directory from another project:
 
-**app/widgets/foo/controllers/widget.js**
-
-```javascript
-const button = Widget.createController('button').getView();
-$.widget.add(button);
+```json
+{
+    "dependencies": {
+        "com.example.rating": "1.0.0"
+    }
+}
 ```
 
-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.
+The generator creates a dependency; inspect it for the actual generated version. A declaration does not fetch files. Copy the widget directory or populate `app/widgets` with a build step, including one from an npm package. The current guide provides no registry workflow.
 
-**app/widgets/foo/controllers/widget.js**
+## Use and communicate
 
-```javascript
-$.init = args => {
-    $.button.title = args.title || 'Yes';
-    $.button.color = args.color || 'black';
-    const message = args.message || 'Hello World';
-}
+```xml
+<Alloy>
+    <Window>
+        <Widget src="com.example.rating" id="rating" score="4" />
+    </Window>
+</Alloy>
 ```
 
-Then, in the Alloy project:
+The widget reads `$.args.score`. Or construct it from JavaScript:
 
 ```javascript
-$.foo.init({title:'Yes', color:'gray', message:'I pity the foo.'});
+const rating = Alloy.createWidget('com.example.rating', { score: 4 });
+$.index.add(rating.getView());
 ```
 
-## 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`.
+The containing view must provide the `$.index` Window. Expose methods with `exports`, and send events with `$.trigger()`:
 
-## 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
+```javascript
+// Widget controller; its view provides a Label with id="stars".
+exports.setScore = (score) => {
+    $.stars.text = '*'.repeat(score);
+};
 ```
 
-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);
+// App controller, after constructing rating.
+rating.setScore(4);
+rating.on('changed', (event) => {
+    Ti.API.info(event.score);
+});
 ```
 
-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>
-```
+The widget emits `$.trigger('changed', { score: 3 })` when its state changes, after listeners have been attached. Events emitted during construction can precede the caller's subscription. Clean up subscriptions with their owning controller.
 
-## Widgets
+## Isolation and styling
 
-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`.
+Keep widget styles and assets with the component and pass values such as `tint` in arguments rather than coupling it to one app's `Alloy.Globals`. The published guide describes stylesheet isolation, but released Alloy 3.0.1 includes matching app `app.tss` rules in widget styles: do not rely on a widget being shielded from global selectors. Use explicit widget styles and deliberate configuration to control its appearance. Keep assets in the widget's own directory; verify exact asset resolution for the target Alloy version when integrating an asset-heavy widget.
 
-To create a widget inside a widget controller, use the `Widget.createWidget(widget_name, [controller_name], [params])` method.
+Source: [widgets](https://titaniumsdk.com/docs/alloy/widgets.md).

package/skills/alloy-howtos/SKILL.md

@@ -1,179 +1,24 @@
 ---
 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.
+description: Use when working on current Titanium Alloy app creation and conversion, config.json runtime settings, environment/platform overrides, compiler constants, widget dependencies, Backbone selection, alloy.jmk hooks, LiveView and build/runtime debugging. Applies to Alloy projects with app/views, app/controllers and app/config.json.
 ---
 
-# alloy-howtos
+# Alloy workflows and configuration
 
-## Overview
+Load the relevant reference before changing an Alloy project's configuration or workflow.
 
-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.
+| Task | Reference |
+| --- | --- |
+| Current conventions, ownership and cleanup | [Practical conventions](references/best_practices.md) |
+| App creation, conversion and supported guide workflows | [CLI workflow](references/cli_reference.md) |
+| config.json, constants, dependencies, themes and hooks | [Configuration](references/config_files.md) |
+| Build errors, logs, breakpoints, LiveView and profiling | [Debugging](references/debugging_troubleshooting.md) |
+| A complete screen and links to persistent-list/widget examples | [Examples](references/samples.md) |
 
-## When to use
+Run `ti info` before diagnosing a toolchain failure as an Alloy defect. Keep secrets out of config files and release logs. Configuration is compiled into the application; environment changes require a build. LiveView handles JavaScript changes, while native configuration/modules require rebuilding.
 
-Use this skill when:
+The currently published configuration page has release-sensitive details. Read the configuration reference's verified caveats before relying on conflicting environment/platform values or selecting a build hook. Confirm the installed Alloy release with `alloy --version`.
 
-- 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
+Use `alloy-guides` for XML, controllers, TSS, models, migrations and widgets; `ti-guides` for SDK setup, modules and distribution; `ti-api` for exact API/platform contracts; and `ti-ui` for native layout/list behavior.
 
-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` |
+Sources: [current Alloy guides](https://titaniumsdk.com/docs/alloy.md), [first app](https://titaniumsdk.com/docs/build/first-app.md), [debugging](https://titaniumsdk.com/docs/build/debugging.md).

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

@@ -1,121 +1,17 @@
-# Alloy best practices and recommendations
+# Practical Alloy conventions
 
-Recommendations for writing Alloy apps. This supplements the Titanium SDK [Best Practices and Recommendations](https://titaniumsdk.com/docs/build) guide and focuses on coding style and conventions.
+Keep structure in XML, shared appearance in `app/styles/app.tss`, screen-specific styles in the corresponding TSS file and behavior in the controller. The controller can still use the Titanium API directly.
 
-## Titanium-to-Alloy Guidance
+Read `$.args` at the top of a controller so its inputs are visible in one place. Share plain code through CommonJS modules in `app/lib`, and initialize shared configuration in `app/alloy.js` before the first controller.
 
-### Loading Libraries in Alloy
+A controller is not a native Window. Construct it, then call `getView().open()`, or expose a method that opens its own Window. Do not combine both opening approaches.
 
-If you need global functionality, require modules in all controllers or create a single global reference:
+Clean up external listeners, timers and service subscriptions when the controller is disposed. Separately call `$.destroy()` to remove generated data bindings. See [controllers](../../alloy-guides/references/CONTROLLERS.md#cleaning-up) for callback ownership and the required lifecycle.
 
-**alloy.js**
-```javascript
-// Alloy.Globals.refToYourModule will be available in all controllers
-Alloy.Globals.refToYourModule = require('yourModule');
-```
+Use widgets for reuse between projects and `<Require>` for composition within one app. Pass widget arguments and report changes through exported methods/events; coupling a reusable widget to the app's global state defeats that isolation.
 
-### Performance Best Practices
+Use models for data that persists, is shared between screens or outlives a screen. A plain array and `Ti.Network` are adequate for data fetched once and rendered. Keep data transforms inexpensive because they run per row when data changes.
 
-The same best practices from traditional Titanium development apply to Alloy. Alloy controllers can do what classic controllers can.
+Do not edit or commit generated `Resources/` or `build/`. Keep signing credentials out of the repository. Do not put secrets in `config.json` or production logs; both reach the app package/device.
 
-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/docs/buildReserved_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.
+Sources: [Alloy](https://titaniumsdk.com/docs/alloy.md), [controllers](https://titaniumsdk.com/docs/alloy/controllers.md), [models](https://titaniumsdk.com/docs/alloy/models.md), [widgets](https://titaniumsdk.com/docs/alloy/widgets.md), [project structure](https://titaniumsdk.com/docs/build/project-structure.md).