@maccesar/titools 2.0.0

package/skills/ti-howtos/references/using-modules.md

@@ -0,0 +1,237 @@
+# Using Modules
+
+Guide for obtaining, installing, and using Titanium modules to extend app functionality.
+
+## Table of Contents
+
+- [Using Modules](#using-modules)
+  - [Table of Contents](#table-of-contents)
+  - [Obtaining Modules](#obtaining-modules)
+    - [Sources of Modules](#sources-of-modules)
+  - [Installing Modules](#installing-modules)
+    - [Single Project Installation](#single-project-installation)
+    - [Global Installation (All Projects)](#global-installation-all-projects)
+  - [Configuring Your App](#configuring-your-app)
+    - [Updating tiapp.xml](#updating-tiappxml)
+    - [Selecting Module Versions](#selecting-module-versions)
+    - [Enable Debugger (for native modules)](#enable-debugger-for-native-modules)
+  - [Using a Module](#using-a-module)
+    - [Loading the Module (ES5)](#loading-the-module-es5)
+    - [Loading the Module (ES6+)](#loading-the-module-es6)
+    - [Using Module Functionality](#using-module-functionality)
+    - [Module Patterns](#module-patterns)
+  - [Troubleshooting](#troubleshooting)
+    - ["Requested module not found"](#requested-module-not-found)
+    - [Version Conflicts](#version-conflicts)
+    - [Platform-Specific Issues](#platform-specific-issues)
+    - [Clean Build](#clean-build)
+  - [Best Practices](#best-practices)
+  - [Module Development](#module-development)
+
+---
+
+## Obtaining Modules
+
+### Sources of Modules
+
+**Official Modules:**
+- **Enterprise Extensions**
+  - InAppBilling (Android)
+  - StoreKit (iOS)
+  - Barcode (iOS/Android)
+  - Compression (iOS/Android)
+  - OpenGL (iOS)
+  - AirPrint (iOS)
+
+**Open-Source Modules:**
+- **GitHub: tidev/** - Official open-source modules
+  - [ti.admob](https://github.com/tidev/ti.admob) - AdMob ads
+  - [ti.map](https://github.com/tidev/ti.map) - Native maps
+  - And many more
+
+**Community Modules:**
+- **From Zero To App** - Lists Titanium modules
+  - https://fromzerotoapp.com/modules/
+- Curated list of modules maintained by Michael Gangolf
+
+**Marketplace:**
+- Appcelerator Marketplace is no longer in use
+- Contact marketplace-admin@axway.com for previously purchased modules
+
+---
+
+## Installing Modules
+
+### Single Project Installation
+
+1. Copy the module ZIP to your app root folder
+2. Add module to `tiapp.xml` (see configuration below)
+3. Build project - ZIP will be extracted automatically
+
+### Global Installation (All Projects)
+
+Modules are installed to platform-specific locations:
+
+| Operating System | Path                                     |
+| ---------------- | ---------------------------------------- |
+| macOS            | `~/Library/Application Support/Titanium` |
+| Windows          | `%ProgramData%\Titanium\mobilesdk\win32` |
+
+**Show hidden Library folder on macOS:**
+```bash
+# Permanently show
+chflags nohidden ~/Library/
+
+# Open once
+open ~/Library
+```
+
+---
+
+## Configuring Your App
+
+### Updating tiapp.xml
+
+**Using Studio/IDE:**
+1. Open `tiapp.xml`
+2. Go to **Overview** tab
+3. Click **+** button in Modules section
+4. Select module and version
+5. Save
+
+**Manually (XML):**
+```xml
+<modules>
+  <module version="3.0.2" platform="ios">ti.map</module>
+  <module version="5.0.0" platform="android">ti.admob</module>
+</modules>
+```
+
+**Attributes:**
+- `version` - Must match module manifest
+- `platform` - "ios" or "android"
+
+### Selecting Module Versions
+
+When multiple versions are installed, you can select specific versions per platform and build type (development/production).
+
+In Studio, double-click the module to open **Module Properties** dialog.
+
+### Enable Debugger (for native modules)
+
+Required for debugging native modules:
+
+```xml
+<ti:app>
+  <android xmlns:android="http://schemas.android.com/apk/res/android">
+    <manifest>
+      <application android:debuggable="true">
+      </application>
+    </manifest>
+  </android>
+</ti:app>
+```
+
+---
+
+## Using a Module
+
+### Loading the Module (ES5)
+
+```javascript
+const Module = require('module.id');
+// Example: const Map = require('ti.map');
+```
+
+### Loading the Module (ES6+)
+
+```javascript
+import Module from 'module.id'
+// Example: import Map from 'ti.map'
+```
+
+**Important:** Don't include `.js` extension in the module ID.
+
+### Using Module Functionality
+
+After requiring, use the module's API:
+
+```javascript
+// ES6+ example with ti.admob
+const Admob = require('ti.admob');
+
+const adview = Admob.createView({
+    top: 0,
+    testing: true,
+    adBackgroundColor: 'black',
+    primaryTextColor: 'blue',
+    publisherId: 'YOUR_PUBLISHER_ID'
+});
+
+win.add(adview);
+```
+
+### Module Patterns
+
+**Singleton pattern:**
+```javascript
+const admob = require('ti.admob');
+admob.createView({...});
+```
+
+**Constructor pattern:**
+```javascript
+const Map = require('ti.map');
+const view = Map.createView({...});
+```
+
+Refer to module documentation for its specific API.
+
+---
+
+## Troubleshooting
+
+### "Requested module not found"
+
+**Solutions:**
+1. Check module ID spelling in `require()`
+2. Verify module is added to `tiapp.xml`
+3. Confirm module is installed (check global or local path)
+4. Remove `version` attribute to use latest version
+
+### Version Conflicts
+
+If multiple versions exist, specify exact version in `tiapp.xml` or remove version attribute to use latest.
+
+### Platform-Specific Issues
+
+- **iOS:** Module must support iOS SDK version you're using
+- **Android:** Check module's `platform` attribute in manifest matches target
+
+### Clean Build
+
+Sometimes needed after installing modules:
+
+```bash
+# Clean and rebuild
+ti clean
+```
+
+---
+
+## Best Practices
+
+1. **Version pinning** - Specify exact module versions for production
+2. **Check compatibility** - Verify module supports your Titanium SDK version
+3. **Test on devices** - Modules may behave differently on simulator vs. device
+4. **Keep updated** - Update modules regularly for bug fixes and new features
+5. **Read documentation** - Each module has specific setup and usage patterns
+
+---
+
+## Module Development
+
+If you need to create your own module, see the **extending-titanium.md** reference for:
+- Android Module Development Guide
+- iOS Module Development Guide
+- Module architecture and best practices

package/skills/ti-howtos/references/web-content-integration.md

@@ -0,0 +1,307 @@
+# Web Content Integration
+
+## Table of Contents
+
+- [Web Content Integration](#web-content-integration)
+  - [Table of Contents](#table-of-contents)
+  - [1. The WebView Component](#1-the-webview-component)
+    - [WKWebView (Titanium SDK 8.0.0+)](#wkwebview-titanium-sdk-800)
+    - [Basic WebView Creation](#basic-webview-creation)
+      - [Remote URL](#remote-url)
+      - [Local HTML](#local-html)
+      - [Inline HTML](#inline-html)
+    - [Local Web Content with Assets](#local-web-content-with-assets)
+    - [WebView Properties and Methods](#webview-properties-and-methods)
+      - [Navigation](#navigation)
+      - [Load Control](#load-control)
+      - [Data Handling](#data-handling)
+      - [Events](#events)
+  - [2. Communication Between WebViews and Titanium](#2-communication-between-webviews-and-titanium)
+    - [Local Web Content Communication](#local-web-content-communication)
+      - [Logging from WebView](#logging-from-webview)
+      - [Bidirectional Events with Ti.App](#bidirectional-events-with-tiapp)
+    - [Remote Web Content Communication](#remote-web-content-communication)
+      - [Using evalJS() for Remote Content](#using-evaljs-for-remote-content)
+      - [Passing Data to Remote Content](#passing-data-to-remote-content)
+  - [3. Performance and Interaction Concerns](#3-performance-and-interaction-concerns)
+    - [WebView Performance](#webview-performance)
+    - [WebView in TableViews](#webview-in-tableviews)
+    - [WebView in Scrollable Components](#webview-in-scrollable-components)
+    - [Viewport Meta Tag](#viewport-meta-tag)
+  - [4. WebView Use Cases](#4-webview-use-cases)
+    - [Authentication Flows](#authentication-flows)
+    - [Canvas and Graphics](#canvas-and-graphics)
+  - [5. WKWebView-Specific Considerations](#5-wkwebview-specific-considerations)
+  - [Best Practices Summary](#best-practices-summary)
+
+---
+
+## 1. The WebView Component
+
+### WKWebView (Titanium SDK 8.0.0+)
+Apple deprecated UIWebView. Titanium now uses WKWebView as the underlying implementation.
+
+**Important**: WKWebView has some behavioral differences compared to the original UIWebView.
+
+### Basic WebView Creation
+
+#### Remote URL
+```javascript
+const webview = Ti.UI.createWebView({
+  url: 'https://titaniumsdk.com'
+});
+win.add(webview);
+win.open();
+```
+
+#### Local HTML
+```javascript
+const webview = Ti.UI.createWebView({
+  url: 'local.html'  // Relative to Resources or app/assets/app/lib
+});
+win.add(webview);
+```
+
+#### Inline HTML
+```javascript
+const webview = Ti.UI.createWebView({
+  html: '<html><body><h1>Hello</h1></body></html>'
+});
+```
+
+### Local Web Content with Assets
+
+Local content can include CSS, JS, and images. Paths are relative to Resources (Classic) or app/assets/app/lib (Alloy).
+
+**local.html**:
+```html
+<html>
+  <head>
+    <link rel="stylesheet" type="text/css" href="local.css"/>
+    <script src="local.js"></script>
+  </head>
+  <body>
+    <p>Local content</p>
+  </body>
+</html>
+```
+
+### WebView Properties and Methods
+
+#### Navigation
+- `canGoBack()` - Returns Boolean if possible to go back
+- `canGoForward()` - Returns Boolean if possible to go forward
+- `goBack()` - Navigate back in history
+- `goForward()` - Navigate forward in history
+
+#### Load Control
+- `loading` (Boolean) - Current loading state
+- `reload()` - Refresh the page
+- `stopLoading()` - Stop loading
+- `repaint()` - Force repaint
+
+#### Data Handling
+- `url` - Local or remote URL
+- `html` - Inline HTML string
+- `scalesPageToFit` - Boolean to scale content to dimensions
+- `setBasicAuthentication(username, password)` - HTTP authentication
+
+#### Events
+- `beforeload` - Fires before loading begins (`e.url` contains the source)
+- `load` - Fires when content has loaded
+- `error` - Fires on load failures (`e.url`, `e.message`)
+
+## 2. Communication Between WebViews and Titanium
+
+### Local Web Content Communication
+
+#### Logging from WebView
+Ti.API methods work inside local HTML:
+
+```html
+<html>
+  <body onload="Ti.API.info('Page loaded!');">
+    <p>Logging works!</p>
+  </body>
+</html>
+```
+
+#### Bidirectional Events with Ti.App
+
+**In local HTML**:
+```html
+<html>
+  <head>
+    <script>
+      // Listen for events from Titanium
+      Ti.App.addEventListener('app:fromTitanium', (e) => {
+        alert(e.message);
+        document.getElementById('output').textContent = e.message;
+      });
+
+      // Send event to Titanium
+      function sendToApp() {
+        Ti.App.fireEvent('app:fromWebView', {
+          message: 'Hello from WebView!'
+        });
+      }
+    </script>
+  </head>
+  <body>
+    <button onclick="sendToApp()">Send to Titanium</button>
+    <div id="output"></div>
+  </body>
+</html>
+```
+
+**In Titanium**:
+```javascript
+const webview = Ti.UI.createWebView({ url: 'local.html' });
+
+// Listen for events from the WebView
+Ti.App.addEventListener('app:fromWebView', (e) => {
+  alert(e.message);
+});
+
+// Send event to the WebView
+const button = Ti.UI.createButton({
+  title: 'Send to WebView'
+});
+button.addEventListener('click', () => {
+  Ti.App.fireEvent('app:fromTitanium', {
+    message: 'Hello from Titanium!'
+  });
+});
+```
+
+### Remote Web Content Communication
+
+**Critical**: Titanium statements (Ti.API, Ti.App) do NOT work in remote HTML content.
+
+#### Using evalJS() for Remote Content
+
+Inject JavaScript and retrieve results as strings:
+
+```javascript
+const webview = Ti.UI.createWebView({ url: 'https://example.com' });
+
+webview.addEventListener('load', (e) => {
+  // Get the page title
+  const title = webview.evalJS('document.title');
+  Ti.API.info(`Page title: ${title}`);
+
+  // Get cookies
+  const cookies = webview.evalJS('document.cookie');
+  Ti.API.info(`Cookies: ${cookies}`);
+
+  // Execute a custom function
+  webview.evalJS('alert("Hello from Titanium!");');
+});
+```
+
+**evalJS() Rules**:
+- Must be called from the `load` event (page must be loaded)
+- Pass code as a single string
+- Returns a string (or null)
+- Use `JSON.stringify()` for complex data
+
+#### Passing Data to Remote Content
+
+```javascript
+webview.addEventListener('load', () => {
+  const data = { user: 'John', score: 100 };
+  webview.evalJS(`window.appData = ${JSON.stringify(data)};`);
+});
+```
+
+Then in the remote HTML:
+```html
+<script>
+  console.log(window.appData.user);  // 'John'
+</script>
+```
+
+## 3. Performance and Interaction Concerns
+
+### WebView Performance
+
+**WebView consumes many resources**:
+- Each WebView requires its own rendering context
+- Significant memory overhead
+- Load time independent of content simplicity
+
+**Best Practice**: If you can recreate the content with native Titanium components, do it.
+
+### WebView in TableViews
+
+**Anti-Pattern**: Embedding WebViews in TableViewRows causes slow scrolling.
+
+### WebView in Scrollable Components
+
+WebViews don't work well inside other scrollable containers (ScrollView, TableView). They consume touch events.
+
+**Workaround**: Set `touchEnabled: false` on the WebView if inside a scrollable parent:
+
+```javascript
+const webview = Ti.UI.createWebView({
+  url: 'content.html',
+  touchEnabled: false  // Allow parent to handle touches
+});
+```
+
+### Viewport Meta Tag
+
+For mobile-optimized content, use the viewport meta tag:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+```
+
+## 4. WebView Use Cases
+
+### Authentication Flows
+Many OAuth providers use WebView for login (like the Facebook module).
+
+```javascript
+const authWebView = Ti.UI.createWebView({
+  url: 'https://auth.example.com/oauth'
+});
+
+authWebView.addEventListener('load', (e) => {
+  // Detect redirect to callback URL with token
+  if (e.url.indexOf('myapp://callback') === 0) {
+    const token = extractTokenFromUrl(e.url);
+    Ti.App.fireEvent('auth:success', { token: token });
+  }
+});
+```
+
+### Canvas and Graphics
+For complex graphics, use HTML5 Canvas:
+
+**local.html**:
+```html
+<canvas id="myCanvas" width="300" height="200"></canvas>
+<script>
+  const ctx = document.getElementById('myCanvas').getContext('2d');
+  ctx.fillStyle = 'green';
+  ctx.fillRect(10, 10, 150, 100);
+</script>
+```
+
+## 5. WKWebView-Specific Considerations
+
+1. **Cookie Management**: WKWebView has separate cookie storage.
+2. **localStorage/SessionStorage**: Not shared with native app.
+3. **Asynchronous evalJS**: In modern iOS versions, async usage is preferred to avoid blocking.
+
+For detailed WKWebView information, refer to the official migration guide and specific behaviors.
+
+## Best Practices Summary
+
+1. **Avoid WebViews when possible** - Use native components.
+2. **Never embed in TableView** - Causes serious scroll issues.
+3. **Use local content for integration** - Only local content supports Ti.App events.
+4. **Use evalJS() for remote** - Only way to interact with remote content.
+5. **Wait for the load event** - Before calling evalJS().
+6. **Configure the viewport** - For proper mobile rendering.

package/skills/ti-howtos/references/webpack-build-pipeline.md

@@ -0,0 +1,78 @@
+# Webpack Build Pipeline
+
+Starting with Titanium SDK 9.1.0, Webpack is the default build engine for managing your project's assets and code.
+
+## Table of Contents
+
+- [Webpack Build Pipeline](#webpack-build-pipeline)
+  - [Table of Contents](#table-of-contents)
+  - [1. Key Benefits](#1-key-benefits)
+  - [2. The `@` Alias](#2-the--alias)
+  - [3. NPM Dependency Management](#3-npm-dependency-management)
+  - [4. Platform-Specific Files](#4-platform-specific-files)
+  - [5. Diagnostic Web UI](#5-diagnostic-web-ui)
+  - [6. Advanced Configuration](#6-advanced-configuration)
+  - [7. Known Limitations](#7-known-limitations)
+
+---
+
+## 1. Key Benefits
+- **Lightning-Fast Incremental Builds**: Only what changes is processed.
+- **Native NPM Support**: Install any NPM library in the root and use it directly.
+- **Build-Time Resolution**: `require` calls are resolved during compilation, not at runtime.
+
+## 2. The `@` Alias
+Webpack introduces the `@` alias to reference the source code root without using complex relative paths (`../../`).
+
+| Project Type | Path mapped by `@` |
+| :----------- | :----------------- |
+| **Alloy**    | `app/lib`          |
+| **Classic**  | `src`              |
+
+**Usage Example:**
+```javascript
+// Before (without webpack)
+import Utils from '../../utils/helper';
+
+// Now (with webpack)
+import Utils from '@/utils/helper';
+```
+
+## 3. NPM Dependency Management
+Simply install your favorite package in the project root:
+```bash
+npm install lodash
+```
+And use it in your Titanium code:
+```javascript
+import _ from 'lodash';
+const data = _.chunk(['a', 'b', 'c', 'd'], 2);
+```
+
+## 4. Platform-Specific Files
+Webpack automatically detects platform-specific files using the `filename.<platform>.js` pattern.
+
+**Example:**
+- `utils.js` (common)
+- `utils.ios.js` (iOS only)
+- `utils.android.js` (Android only)
+
+When doing `import { func } from '@/utils'`, Webpack will select the correct version based on the build target.
+
+## 5. Diagnostic Web UI
+Webpack includes a web interface to analyze the build and asset sizes.
+Default URL: `http://localhost:1732/webpack/latest/web`
+
+## 6. Advanced Configuration
+You can extend the configuration via plugins in `package.json`:
+```json
+{
+  "appcdWebpackPlugins": [
+    "my-local-plugin.js"
+  ]
+}
+```
+
+## 7. Known Limitations
+- **Hyperloop**: Currently not compatible with the Webpack pipeline.
+- **Alloy.jmk**: Older makefiles are ignored by Webpack.