@maccesar/titools 3.3.0 → 4.0.0

package/skills/ti-howtos/references/tutorials.md

@@ -0,0 +1,552 @@
+# Titanium SDK tutorials
+
+Practical tutorials and guides for building real Titanium applications.
+
+## RESTe - API integration
+
+### Overview
+RESTe by Jason Kneen is a module for consuming web APIs in Titanium.
+
+Benefits:
+- Eliminates boilerplate HTTP code
+- Auto-generates JavaScript API from config
+- Supports Backbone.js models and collections in Alloy
+- Works with any API (not just REST)
+
+### Installation
+
+```bash
+npm install reste
+```
+
+### Basic configuration
+
+`alloy.js`:
+
+```javascript
+const reste = require('reste');
+const api = new reste();
+
+api.config({
+  debug: true, // Console logging
+  errorsAsObjects: true, // Return errors as objects (1.4.5+) - breaks apps written for 1.4.4 that handle errors differently
+  autoValidateParams: false, // Throw error if params missing
+  validatesSecureCertificate: false,
+  timeout: 4000,
+  url: 'https://api.example.com/', // Base URL
+  requestHeaders: {
+    'X-API-Key': 'your-key-here',
+    'Content-Type': 'application/json'
+  },
+  methods: [
+    {
+      name: 'getVideos',
+      get: 'videos'
+    },
+    {
+      name: 'getVideoById',
+      get: 'videos/'
+    },
+    {
+      name: 'createVideo',
+      post: 'videos'
+    }
+  ],
+  onError: (e, retry) => {
+    const dialog = Ti.UI.createAlertDialog({
+      title: 'Connection error',
+      message: 'Check your network and retry.',
+      buttonNames: ['Retry']
+    });
+    dialog.addEventListener('click', () => {
+      retry();
+    });
+    dialog.show();
+  }
+});
+```
+
+### Usage
+
+Auto-generated methods:
+
+```javascript
+// Fetch single video
+api.getVideoById({
+  videoId: 'abc123'
+}, (video) => {
+  Ti.API.info(`Got video: ${video.title}`);
+});
+
+// Create video
+api.createVideo({
+  body: {
+    title: 'My Video',
+    categoryId: 2
+  }
+}, (response) => {
+  Ti.API.info(`Created: ${response.id}`);
+});
+```
+
+### Backbone.js models and collections
+
+Configuration:
+
+```javascript
+api.config({
+  // ... other config
+  models: [{
+    name: 'video',
+    id: 'objectId', // Primary key field
+    read: 'getVideo',
+    create: 'createVideo',
+    update: 'updateVideo',
+    delete: 'deleteVideo',
+    collections: [{
+      name: 'videos',
+      content: 'results', // Array wrapper in response
+      read: 'getVideos'
+    }]
+  }]
+});
+```
+
+In an Alloy controller:
+
+```javascript
+// Fetch collection
+Alloy.Collections.videos.fetch();
+
+// Or fetch with parameters
+Alloy.Collections.videos.fetch({
+  data: { category: 'sports' }
+});
+```
+
+In an Alloy view:
+
+```xml
+<TableView dataCollection="videos" onClick="selectVideo">
+  <TableViewRow model="{objectId}">
+    <Label class="title" text="{title}"/>
+    <Label class="subtitle" text="{description}"/>
+  </TableViewRow>
+</TableView>
+```
+
+### RESTe advanced features
+
+- Caching: built-in response caching
+- Promises: use with `q.js` for Promise-based API calls
+- Mock data: create models and collections on the fly for testing
+
+```javascript
+const mockUser = api.createModel('users', {
+  id: 1,
+  name: 'Test User'
+});
+```
+
+- Backbone.js binding: use RESTe models directly with Alloy data binding without `<Model>` tags
+
+### Important notes
+
+- Do not use `<Model>` or `<Collection>` tags with RESTe
+- RESTe creates models and collections automatically
+- Use data binding like normal Alloy collections
+- Useful for mocking data during UI development
+
+### Mock data (on the fly)
+
+```javascript
+// Create model without API
+const videoModel = api.createModel('video', {
+  title: 'Test Video',
+  description: 'Mock data'
+});
+
+// Create collection
+const videoCollection = api.createCollection('videos', [
+  { title: 'Video 1' },
+  { title: 'Video 2' }
+]);
+```
+
+### Resources
+
+- npm: https://www.npmjs.com/package/reste
+- GitHub: https://github.com/jasonkneen/reste
+
+---
+
+## Camera app tutorial
+
+### Camera permissions setup
+
+iOS - add to `tiapp.xml` plist:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>This app needs camera access to take photos</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>This app needs microphone access for video recording</string>
+```
+
+Android: camera permissions are automatically added by the build system when you use `Ti.Media.showCamera()`.
+
+Always check permissions at runtime:
+
+```javascript
+if (!Ti.Media.hasCameraPermissions()) {
+  Ti.Media.requestCameraPermissions((e) => {
+    if (e.success) openCamera();
+  });
+} else {
+  openCamera();
+}
+```
+
+### Basic camera access
+
+```javascript
+// Show camera
+Ti.Media.showCamera({
+  success: (event) => {
+    const image = event.media;
+    if (event.mediaType === Ti.Media.MEDIA_TYPE_PHOTO) {
+      // Use the photo
+      const imageView = Ti.UI.createImageView({
+        image: image,
+        width: 300,
+        height: 300
+      });
+      win.add(imageView);
+    }
+  },
+  cancel: () => {
+    Ti.API.info('Camera canceled');
+  },
+  error: (error) => {
+    const a = Ti.UI.createAlertDialog({ title: 'Camera Error' });
+    if (error.code === Ti.Media.NO_CAMERA) {
+      a.setMessage('Device does not have camera');
+    } else {
+      a.setMessage(`Unexpected error: ${error.code}`);
+    }
+    a.show();
+  },
+  saveToPhotoGallery: true,
+  allowEditing: true,
+  mediaTypes: [Ti.Media.MEDIA_TYPE_PHOTO],
+  videoQuality: Ti.Media.QUALITY_HIGH
+});
+```
+
+### Photo gallery
+
+```javascript
+// Open photo gallery
+Ti.Media.openPhotoGallery({
+  success: (event) => {
+    const image = event.media;
+    // Process selected image
+  },
+  cancel: () => {
+    // User canceled
+  },
+  error: (error) => {
+    // Handle error
+  },
+  mediaTypes: [Ti.Media.MEDIA_TYPE_PHOTO]
+});
+```
+
+### Saving images
+
+```javascript
+// Save to gallery
+Ti.Media.saveToPhotoGallery({
+  media: myImageBlob,
+  success: () => {
+    alert('Saved!');
+  },
+  error: (e) => {
+    alert(`Error: ${e.error}`);
+  }
+});
+```
+
+---
+
+## Geolocation tutorial
+
+### Geolocation permissions setup
+
+iOS - add to `tiapp.xml` plist:
+
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>We need your location to show nearby places</string>
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>We need your location for background tracking</string>
+```
+
+Android - add to `tiapp.xml` manifest:
+
+```xml
+<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
+<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
+```
+
+Runtime permission check:
+```javascript
+if (!Ti.Geolocation.hasLocationPermissions(Ti.Geolocation.AUTHORIZATION_WHEN_IN_USE)) {
+  Ti.Geolocation.requestLocationPermissions(Ti.Geolocation.AUTHORIZATION_WHEN_IN_USE, (e) => {
+    if (e.success) startTracking();
+  });
+}
+```
+
+### Basic location
+
+```javascript
+// One-time location
+if (Ti.Geolocation.locationServicesEnabled) {
+  Ti.Geolocation.getCurrentPosition((e) => {
+    if (!e.error) {
+      Ti.API.info(`Lat: ${e.coords.latitude}`);
+      Ti.API.info(`Lon: ${e.coords.longitude}`);
+    }
+  });
+}
+```
+
+### Continuous tracking
+
+```javascript
+// Configure accuracy
+Ti.Geolocation.accuracy = Ti.Geolocation.ACCURACY_BEST;
+Ti.Geolocation.distanceFilter = 10; // Meters
+
+// Track location changes
+Ti.Geolocation.addEventListener('location', (e) => {
+  if (!e.error) {
+    const lat = e.coords.latitude;
+    const lon = e.coords.longitude;
+    updateMap(lat, lon);
+  }
+});
+```
+
+### Reverse geocoding
+
+```javascript
+// Coordinates to address
+Ti.Geolocation.reverseGeocoder(37.389569, -122.050212, (e) => {
+  if (e.success) {
+    e.places.forEach((place) => {
+      Ti.API.info(place.address);
+      Ti.API.info(place.city);
+      Ti.API.info(place.country);
+    });
+  }
+});
+```
+
+### Accuracy tuning
+
+```javascript
+// iOS: minimum distance before firing event
+Ti.Geolocation.distanceFilter = 10; // meters
+
+// Android: use FusedLocationProvider for better battery (requires ti.playservices module)
+// Automatically enabled with SDK 7.1.0+ when ti.playservices is present
+
+// Android: custom location rules
+Ti.Geolocation.Android.addLocationRule(Ti.Geolocation.Android.createLocationRule({
+  provider: Ti.Geolocation.Android.PROVIDER_GPS,
+  accuracy: 100, // meters
+  minAge: 1000 // milliseconds
+}));
+```
+
+---
+
+## Alloy controller chaining
+
+### Pattern overview
+
+Chain controller methods to pass data between Alloy controllers in a clean, maintainable way.
+
+### Basic pattern
+
+Parent controller:
+```javascript
+const childController = Alloy.createController('child', {
+  data: someData,
+  onAction: (result) => {
+    // Handle result from child
+    Ti.API.info(`Child returned: ${result}`);
+  }
+});
+
+childController.on('customEvent', (data) => {
+  // Handle child events
+});
+
+childController.open();
+```
+
+Child controller:
+```javascript
+const args = arguments[0] || {};
+
+// Access parent data
+const parentData = args.data;
+
+// Call parent callback
+function notifyParent(result) {
+  if (args.onAction) {
+    args.onAction(result);
+  }
+}
+
+// Trigger parent events
+function triggerEvent(data) {
+  $.trigger('customEvent', data);
+}
+```
+
+### Benefits
+
+- Clean separation. Controllers remain independent.
+- Reusable. Child works in different contexts.
+- Testable. You can mock parent callbacks.
+- Maintainable. Clear data flow.
+
+---
+
+## Build automation with Fastlane
+
+### Overview
+
+Automate building and deploying Titanium apps with Fastlane.
+
+### Installing Fastlane
+
+```bash
+# Using Homebrew (macOS)
+brew install fastlane
+
+# Or using Ruby gems
+sudo gem install fastlane -NV
+```
+
+### Basic Fastfile
+
+`fastlane/Fastfile`:
+```ruby
+platform :ios do
+  desc "Build and deploy to TestFlight"
+  lane :beta do
+    # Build the app
+    sh "ti build -p ios -F"
+
+    # Upload to TestFlight
+    upload_to_testflight(
+      skip_waiting_for_build_processing: true
+    )
+  end
+
+  desc "Build for development"
+  lane :dev do
+    sh "ti build -p ios -T developer"
+  end
+end
+
+platform :android do
+  desc "Build Android APK"
+  lane :build do
+    sh "ti build -p android -A"
+  end
+
+  desc "Deploy to Play Store (Beta)"
+  lane :beta do
+    # Build
+    sh "ti build -p android -F"
+
+    # Upload to Play Store
+    upload_to_play_store(
+      track: 'beta',
+      apk: 'app/build/android/bin/app.apk'
+    )
+  end
+end
+```
+
+### Usage
+
+```bash
+# iOS Beta
+fastlane ios beta
+
+# Android Build
+fastlane android build
+
+# Android Beta
+fastlane android beta
+```
+
+### Advanced options
+
+Multiple environments:
+```ruby
+lane :staging do
+  sh "ti build -p ios -T dist --config ../staging.js"
+end
+
+lane :production do
+  sh "ti build -p ios -T dist --config ../production.js"
+end
+```
+
+Environment-specific configs:
+```javascript
+// staging.js
+module.exports = {
+  apiURL: 'https://staging-api.example.com',
+  analyticsEnabled: true
+};
+
+// production.js
+module.exports = {
+  apiURL: 'https://api.example.com',
+  analyticsEnabled: true
+};
+```
+
+---
+
+## Additional tutorials
+
+### Alloy boilerplates
+
+See `Titanium_Boilerplates` folder for:
+- TypeScript boilerplates
+- App templates
+- Project scaffolding
+
+### Complete sample apps
+
+- ToDoList - CommonJS module pattern example
+- Tweetanium - Namespaced pattern example
+- KitchenSink - Complete API reference (built with Alloy)
+
+---
+
+## Resources
+
+- RESTe: https://github.com/jasonkneen/reste
+- Fastlane: https://fastlane.tools
+- Alloy Framework: see alloy-guides skill

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

@@ -0,0 +1,182 @@
+# Using modules
+
+Guide to obtaining, installing, and using Titanium modules to extend app functionality.
+
+## 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
+  - 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 list: https://fromzerotoapp.com/modules/
+- Curated list of modules maintained by Michael Gangolf
+
+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 do not need separate installation: `ti.map`, `ti.identity`, `ti.webdialog`, `ti.applesignin`.
+
+## 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.
+
+### Global installation (all projects)
+Modules install 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 the Overview tab.
+3. Click the plus button in Modules.
+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 the module manifest
+- `platform`: "ios" or "android"
+
+### Selecting module versions
+If multiple versions are installed, select specific versions per platform and build type (development/production).
+
+In Studio, double-click the module to open the 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: do not include the `.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 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.
+
+### Version conflicts
+If multiple versions exist, specify the exact version in `tiapp.xml`, or remove the version attribute to use the latest.
+
+### 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
+# Clean and rebuild
+ti clean
+```
+
+## 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.