@maccesar/titools 5.3.0 → 5.4.0

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

@@ -1,233 +1,34 @@
-# Alloy Tasks with the CLI
+# Create and run an Alloy app
 
-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.
+Check the toolchain with `ti info` and finish environment setup before diagnosing a failed build as an Alloy problem.
 
 ```bash
-ti create -t app --classic -i com.appc.picker -n AlloyPicker
-cd AlloyPicker
-alloy new --testapp ui/picker
+npm install -g alloy
+ti create --type app --alloy --name Hello --id com.example.hello --platforms android,ios --workspace-dir .
+cd Hello
+ti build --platform android
 ```
 
-## Generating Components
-
-The CLI can generate skeleton controllers (with views and styles), models, database migrations and widgets.
+Use a reverse-DNS app ID from a domain you control: changing it after publication means a new listing in both stores. `--name` chooses the directory and icon label. `ios` selects iPhone and iPad; `iphone` selects iPhone only. In noninteractive creation, supply `--type` and `--workspace-dir` as shown; `ti create` without arguments prompts.
 
-### Generating a Controller
+`--alloy` invokes `alloy new` after creating the project. Alloy must be on `PATH`; otherwise the project remains Classic and the CLI reports what to install. To convert an existing Classic project, run `alloy new` in its root.
 
-To generate a controller with a style and view:
+## Build and iterate
 
 ```bash
-alloy generate controller <name> [--widgetname <widget_name>] [-o path_to_project/app] [--platform <platform>]
+ti build --platform ios
+ti build --platform android --build-only
+ti build --platform android --liveview
 ```
 
-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
+Default targets are Android emulator and iOS simulator. With several available devices, the CLI prompts; use `--device-id` to choose explicitly. iOS builds require macOS and Xcode. Initial native builds are slower than incremental builds. A successful build reports `Project built successfully`; terminal logs continue until Ctrl-C. `--build-only` skips installation and launch; LiveView reloads JavaScript on save.
 
-### Installing the Compiler Plugin
+For real devices, use `--target device`. Android needs developer options, USB debugging and USB authorization; check `ti info -t android`. iOS needs a development certificate and a matching provisioning profile containing the device; connect, unlock and trust the Mac. Select a UDID from `ti info -t ios` with `--device-id`. Use `ti-guides` for full setup and signing.
 
-To install the compiler plugin that hooks the Alloy project to Studio:
+To generate the widget described by the current guide:
 
 ```bash
-alloy install plugin [path_to_project]
+alloy generate widget com.example.rating
 ```
 
-Use this command to update the compiler plugin if your project was created using an older version of Alloy.
+Sources: [first app](https://titaniumsdk.com/docs/build/first-app.md), [Alloy](https://titaniumsdk.com/docs/alloy.md), [widgets](https://titaniumsdk.com/docs/alloy/widgets.md).

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

@@ -1,171 +1,36 @@
-# Alloy Concepts
+# Alloy concepts and project structure
 
-## Overview
+Alloy is Titanium's MVC framework. A screen normally has an XML view for structure, a TSS file for style and a JavaScript controller for behavior. Alloy compiles them into ordinary Titanium JavaScript before the native build; the underlying Titanium API remains available.
 
-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.
+Install Alloy separately with `npm install -g alloy`. Use Alloy for applications with several screens, shared styles, reusable controllers/widgets or persistent models. Classic is plain Titanium JavaScript and suits prototypes or small tools. `alloy new` converts an existing Classic project in place.
 
-## Model-View-Controller
+## Files and ownership
 
-Alloy uses the model-view-controller (MVC) pattern, which separates the application into three different components:
+| Path | Purpose |
+| --- | --- |
+| `app/views/index.xml` | Initial XML hierarchy |
+| `app/styles/app.tss` | Styles shared across the app |
+| `app/styles/index.tss` | Styles for `index.xml` |
+| `app/controllers/index.js` | Initial controller behavior |
+| `app/models/` | Backbone model definitions and collections |
+| `app/widgets/` | Reusable components |
+| `app/lib/` | Plain CommonJS modules |
+| `app/assets/` | Images and `semantic.colors.json` |
+| `app/platform/` | Files copied into the native project |
+| `app/themes/` | Build-time themes |
+| `app/alloy.js` | Initializer, before the first controller |
+| `app/config.json` | Application settings and compiler configuration |
+| `plugins/ti.alloy/` | Compiler hook installed by `alloy new` |
+| `tiapp.xml` | App identity, SDK, native configuration and deployment targets |
+| `Resources/` | Generated output; never edit it |
+| `build/` | Generated native project and compiled output |
 
-* **Models** provide the business logic, containing the rules, data and state of the application
+Assets are referenced relative to `app/assets`: `app/assets/images/logo.png` becomes `images/logo.png`. Use `app/assets/android` and `app/assets/iphone` for platform-specific assets; only the matching assets enter the package. Native files under `app/platform` are copied without processing.
 
-* **Views** provide the GUI components to the user, either presenting data or allowing the user to interact with the model data
+Commit source, assets, `tiapp.xml` and `DefaultIcon.png`. Do not commit `build/`, generated `Resources/`, or top-level `platform/` and `i18n/` in an Alloy project. `alloy new` writes their ignore rules. Keep keystores and signing credentials out of the repository.
 
-* **Controllers** provide the glue between the model and view components in the form of application logic
+The Classic template's initial `Resources/app.js` can remain after conversion; subsequent Alloy builds replace generated output. Do not change it to implement an Alloy screen.
 
-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.
+For app identity, native permissions and signing, use `ti-guides`. For the view/controller/style relationship, read [XML views](./VIEWS_XML.md), [styles](./VIEWS_STYLES.md) and [controllers](./CONTROLLERS.md).
 
-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.
+Sources: [Alloy](https://titaniumsdk.com/docs/alloy.md), [project structure](https://titaniumsdk.com/docs/build/project-structure.md), [first app](https://titaniumsdk.com/docs/build/first-app.md).