@maccesar/titools 2.2.4 → 2.2.8

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

@@ -1,13 +1,13 @@
-# Using Modules
+# Using modules
 
-Guide for obtaining, installing, and using Titanium modules to extend app functionality.
+Guide to obtaining, installing, and using Titanium modules to extend app functionality.
 
-## Obtaining Modules
+## Obtaining modules
 
-### Sources of Modules
+### Sources of modules
 
-**Official Modules:**
-- **Enterprise Extensions**
+Official modules:
+- Enterprise Extensions
   - InAppBilling (Android)
   - StoreKit (iOS)
   - Barcode (iOS/Android)
@@ -15,43 +15,39 @@ Guide for obtaining, installing, and using Titanium modules to extend app functi
   - 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
+Open-source modules:
+- GitHub: tidev
+  - https://github.com/tidev/ti.admob - AdMob ads
+  - https://github.com/tidev/ti.map - Native maps
+  - And more in the org
 
-**Community Modules:**
-- **From Zero To App** - Lists Titanium modules
-  - https://fromzerotoapp.com/modules/
+Community modules:
+- From Zero To App list: https://fromzerotoapp.com/modules/
 - Curated list of modules maintained by Michael Gangolf
 
-**Marketplace:**
-> **Note**: The original Appcelerator Marketplace is no longer available. Find community modules on GitHub and npm. A curated list is at [From Zero to App](https://fromzerotoapp.com/modules/).
+Marketplace:
+The original Appcelerator Marketplace is no longer available. Find community modules on GitHub and npm. A curated list is at https://fromzerotoapp.com/modules/.
 
-### Pre-installed Modules
-Some modules ship with the SDK and don't need separate installation: `ti.map`, `ti.identity`, `ti.webdialog`, `ti.applesignin`
+### Pre-installed modules
+Some modules ship with the SDK and do not need separate installation: `ti.map`, `ti.identity`, `ti.webdialog`, `ti.applesignin`.
 
----
+## Installing modules
 
-## Installing Modules
+### Single project installation
+1. Copy the module ZIP to your app root folder.
+2. Add the module to `tiapp.xml` (see configuration below).
+3. Build the project. The ZIP is extracted automatically.
 
-### Single Project Installation
+### Global installation (all projects)
+Modules install to platform-specific locations:
 
-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                                     |
+| Operating system | Path                                     |
 | ---------------- | ---------------------------------------- |
 | macOS            | `~/Library/Application Support/Titanium` |
 | Windows          | `%ProgramData%\Titanium\mobilesdk\win32` |
 
-**Show hidden Library folder on macOS:**
+Show hidden Library folder on macOS:
+
 ```bash
 # Permanently show
 chflags nohidden ~/Library/
@@ -60,20 +56,19 @@ chflags nohidden ~/Library/
 open ~/Library
 ```
 
----
-
-## Configuring Your App
+## 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
+Using Studio/IDE:
+1. Open `tiapp.xml`.
+2. Go to the Overview tab.
+3. Click the plus button in Modules.
+4. Select module and version.
+5. Save.
+
+Manually (XML):
 
-**Manually (XML):**
 ```xml
 <modules>
   <module version="3.0.2" platform="ios">ti.map</module>
@@ -81,18 +76,16 @@ open ~/Library
 </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).
+Attributes:
+- `version`: must match the module manifest
+- `platform`: "ios" or "android"
 
-In Studio, double-click the module to open **Module Properties** dialog.
+### Selecting module versions
+If multiple versions are installed, select specific versions per platform and build type (development/production).
 
-### Enable Debugger (for native modules)
+In Studio, double-click the module to open the Module Properties dialog.
 
+### Enable debugger (for native modules)
 Required for debugging native modules:
 
 ```xml
@@ -106,28 +99,25 @@ Required for debugging native modules:
 </ti:app>
 ```
 
----
+## Using a module
 
-## Using a Module
-
-### Loading the Module (ES5)
+### Loading the module (ES5)
 
 ```javascript
 const Module = require('module.id');
 // Example: const Map = require('ti.map');
 ```
 
-### Loading the Module (ES6+)
+### 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
+Important: do not include the `.js` extension in the module ID.
 
+### Using module functionality
 After requiring, use the module's API:
 
 ```javascript
@@ -135,55 +125,49 @@ After requiring, use the module's API:
 const Admob = require('ti.admob');
 
 const adview = Admob.createView({
-    top: 0,
-    testing: true,
-    adBackgroundColor: 'black',
-    primaryTextColor: 'blue',
-    publisherId: 'YOUR_PUBLISHER_ID'
+  top: 0,
+  testing: true,
+  adBackgroundColor: 'black',
+  primaryTextColor: 'blue',
+  publisherId: 'YOUR_PUBLISHER_ID'
 });
 
 win.add(adview);
 ```
 
-### Module Patterns
+### Module patterns
 
-**Singleton pattern:**
+Singleton pattern:
 ```javascript
 const admob = require('ti.admob');
-admob.createView({...});
+admob.createView({ ... });
 ```
 
-**Constructor pattern:**
+Constructor pattern:
 ```javascript
 const Map = require('ti.map');
-const view = Map.createView({...});
+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 the module is added to `tiapp.xml`.
+3. Confirm the module is installed (global or local path).
+4. Remove the `version` attribute to use the latest version.
 
-**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
+### Version conflicts
+If multiple versions exist, specify the exact version in `tiapp.xml`, or remove the version attribute to use the latest.
 
-### Clean Build
+### Platform-specific issues
+- iOS: the module must support the iOS SDK version you are using.
+- Android: the module manifest `platform` must match the target.
 
+### Clean build
 Sometimes needed after installing modules:
 
 ```bash
@@ -191,21 +175,8 @@ Sometimes needed after installing modules:
 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
+## Best practices
 
-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
+1. Pin versions for production.
+2. Check compatibility with your Titanium SDK version.
+3. Test on devices. Some modules behave differently on simulator vs device.

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

@@ -1,14 +1,13 @@
-# Web Content Integration
+# Web content integration
 
-## 1. The WebView Component
+## 1. The WebView component
 
 ### WKWebView (Titanium SDK 8.0.0+)
+As of Titanium SDK 8.0.0, WKWebView is the only supported web view on iOS. UIWebView was deprecated and removed. WKWebView behaves differently, so plan for that.
 
-> **Important**: As of Titanium SDK 8.0.0, WKWebView is the only supported web view on iOS. Apple deprecated UIWebView and it has been removed. WKWebView has behavioral differences you must account for.
+### Basic WebView creation
 
-### Basic WebView Creation
-
-#### Remote URL
+Remote URL:
 ```javascript
 const webview = Ti.UI.createWebView({
   url: 'https://titaniumsdk.com'
@@ -17,26 +16,25 @@ win.add(webview);
 win.open();
 ```
 
-#### Local HTML
+Local HTML:
 ```javascript
 const webview = Ti.UI.createWebView({
-  url: 'local.html'  // Relative to Resources or app/assets/app/lib
+  url: 'local.html' // Relative to Resources or app/assets/app/lib
 });
 win.add(webview);
 ```
 
-#### Inline HTML
+Inline HTML:
 ```javascript
 const webview = Ti.UI.createWebView({
   html: '<html><body><h1>Hello</h1></body></html>'
 });
 ```
 
-### Local Web Content with Assets
-
+### 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**:
+`local.html`:
 ```html
 <html>
   <head>
@@ -49,40 +47,41 @@ Local content can include CSS, JS, and images. Paths are relative to Resources (
 </html>
 ```
 
-### WebView Properties and Methods
+### WebView properties and methods
+
+Navigation:
+- `canGoBack()` - returns true if possible to go back
+- `canGoForward()` - returns true if possible to go forward
+- `goBack()` - navigate back in history
+- `goForward()` - navigate forward in history
 
-#### 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
 
-#### 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` - scale content to dimensions
+- `setBasicAuthentication(host, username, password)` - HTTP auth
 
-#### Data Handling
-- `url` - Local or remote URL
-- `html` - Inline HTML string
-- `scalesPageToFit` - Boolean to scale content to dimensions
-- `setBasicAuthentication(host, username, password)` - HTTP authentication
-  ```javascript
-  webView.setBasicAuthentication('myDomain.com', 'username', 'password');
-  ```
+```javascript
+webView.setBasicAuthentication('myDomain.com', 'username', 'password');
+```
 
-#### 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`)
+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
+## 2. Communication between WebViews and Titanium
 
-### Local Web Content Communication
+### Local web content communication
 
-#### Logging from WebView
-Ti.API methods work inside local HTML:
+Logging from WebView:
+Ti.API methods work inside local HTML.
 
 ```html
 <html>
@@ -92,9 +91,9 @@ Ti.API methods work inside local HTML:
 </html>
 ```
 
-#### Bidirectional Events with Ti.App
+Bidirectional events with `Ti.App`:
 
-**In local HTML**:
+In local HTML:
 ```html
 <html>
   <head>
@@ -120,7 +119,7 @@ Ti.API methods work inside local HTML:
 </html>
 ```
 
-**In Titanium**:
+In Titanium:
 ```javascript
 const webview = Ti.UI.createWebView({ url: 'local.html' });
 
@@ -140,14 +139,13 @@ button.addEventListener('click', () => {
 });
 ```
 
-### Remote Web Content Communication
-
-**Critical**: Titanium statements (Ti.API, Ti.App) do NOT work in remote HTML content.
+### Remote web content communication
 
-> **Warning**: On iOS 12.0+, calling `evalJS()` synchronously from certain contexts can cause a deadlock. Always prefer the callback-based async version.
+Titanium statements (`Ti.API`, `Ti.App`) do not work in remote HTML content.
 
-#### Using evalJS() for Remote Content
+Warning: On iOS 12.0+, calling `evalJS()` synchronously from some contexts can deadlock. Prefer the async version with a callback.
 
+#### Using `evalJS()` for remote content
 Inject JavaScript and retrieve results as strings:
 
 ```javascript
@@ -167,13 +165,13 @@ webview.addEventListener('load', (e) => {
 });
 ```
 
-**evalJS() Rules**:
-- Must be called from the `load` event (page must be loaded)
+`evalJS()` rules:
+- Call it 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
+#### Passing data to remote content
 
 ```javascript
 webview.addEventListener('load', () => {
@@ -182,59 +180,55 @@ webview.addEventListener('load', () => {
 });
 ```
 
-Then in the remote HTML:
+Then in remote HTML:
 ```html
 <script>
-  console.log(window.appData.user);  // 'John'
+  console.log(window.appData.user); // 'John'
 </script>
 ```
 
-## 3. Performance and Interaction Concerns
+## 3. Performance and interaction concerns
 
-### WebView Performance
+### WebView performance
+WebView consumes significant resources:
+- Each WebView has its own rendering context
+- Memory overhead is high
+- Load time is independent of content complexity
 
-**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.
+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.
 
-**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.
+### WebView in scrollable components
+WebViews do not behave well inside other scrollable containers (ScrollView, TableView). They consume touch events.
 
-**Workaround**: Set `touchEnabled: false` on the WebView if inside a scrollable parent:
+Workaround: set `touchEnabled: false` on the WebView if it sits inside a scrollable parent:
 
 ```javascript
 const webview = Ti.UI.createWebView({
   url: 'content.html',
-  touchEnabled: false  // Allow parent to handle touches
+  touchEnabled: false // Allow parent to handle touches
 });
 ```
 
-### Viewport Meta Tag
-
+### 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
+## 4. WebView use cases
 
-### Common WebView Use Cases
-- **HTML forms**: WebViews provide auto-scroll to focused fields, next/previous navigation, and native keyboard integration — often better than building forms in native UI.
-- **Rich text / HTML email**: Render styled content that would be difficult with native labels.
-- **Canvas / graphics**: HTML5 Canvas provides 2D drawing capabilities not available in native Titanium APIs.
-- **OAuth flows**: Load third-party auth pages (Google, Facebook) inside a WebView and intercept redirects.
+Common WebView use cases:
+- HTML forms: auto-scroll to focused fields, next/previous navigation, native keyboard integration
+- Rich text or HTML email: render styled content that is hard to replicate with native labels
+- Canvas/graphics: HTML5 Canvas provides 2D drawing not available in native Titanium APIs
+- OAuth flows: load third-party auth pages in a WebView and intercept redirects
 
-### Authentication Flows
-Many OAuth providers use WebView for login (like the Facebook module).
+### Authentication flows
+Many OAuth providers use WebView for login (for example, the Facebook module).
 
 ```javascript
 const authWebView = Ti.UI.createWebView({
@@ -250,10 +244,10 @@ authWebView.addEventListener('load', (e) => {
 });
 ```
 
-### Canvas and Graphics
+### Canvas and graphics
 For complex graphics, use HTML5 Canvas:
 
-**local.html**:
+`local.html`:
 ```html
 <canvas id="myCanvas" width="300" height="200"></canvas>
 <script>
@@ -263,28 +257,32 @@ For complex graphics, use HTML5 Canvas:
 </script>
 ```
 
-## 5. WKWebView Behavioral Differences (iOS)
+## 5. WKWebView behavioral differences (iOS)
 
-- **Cookies**: WKWebView uses a separate cookie store from `Ti.Network`. Cookies set via HTTPClient are not automatically shared with WebViews.
-- **localStorage/sessionStorage**: NOT shared between the native app and the WebView. Each WKWebView has its own storage.
-- **evalJS is async**: On iOS 12.0+, synchronous `evalJS()` can cause deadlocks. Use the callback form instead:
-  ```javascript
-  webView.evalJS('document.title', (result) => {
-      Ti.API.info(`Title: ${result}`);
-  });
-  ```
-- **Viewport meta tag required**: WKWebView requires an explicit viewport tag to scale content properly:
-  ```html
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  ```
-- **Custom fonts**: Must use a special `@font-face` path format in WKWebView CSS. Fonts must be in the app bundle and referenced correctly.
-- **Remote HTML limitations**: `Ti.API`, `Ti.App.fireEvent()`, and other Titanium calls do NOT work in remotely-loaded HTML pages. Only local HTML files can communicate with the Titanium runtime.
-
-## 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.
+- Cookies: WKWebView uses a separate cookie store from `Ti.Network`. Cookies set via HTTPClient are not shared with WebViews.
+- `localStorage`/`sessionStorage`: not shared between the native app and the WebView. Each WKWebView has its own storage.
+- `evalJS` is async: on iOS 12.0+, synchronous `evalJS()` can deadlock. Use the callback form instead:
+
+```javascript
+webView.evalJS('document.title', (result) => {
+  Ti.API.info(`Title: ${result}`);
+});
+```
+
+- Viewport meta tag required: WKWebView needs an explicit viewport tag to scale content correctly:
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+```
+
+- Custom fonts: use a special `@font-face` path format in WKWebView CSS. Fonts must be in the app bundle and referenced correctly.
+- Remote HTML limitations: `Ti.API`, `Ti.App.fireEvent()`, and other Titanium calls do not work in remotely-loaded HTML. Only local HTML can communicate with the Titanium runtime.
+
+## Best practices summary
+
+1. Avoid WebViews when possible. Use native components.
+2. Never embed a WebView in a TableView.
+3. Use local content for integration. Only local content supports `Ti.App` events.
+4. Use `evalJS()` for remote content. It is the only way to interact with remote pages.
+5. Wait for the `load` event before calling `evalJS()`.
+6. Configure the viewport for proper mobile rendering.