@maccesar/titools 5.3.0 → 5.4.0

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

@@ -1,565 +0,0 @@
-# Titanium SDK tutorials
-
-Practical tutorials and guides for building real Titanium applications.
-
-<!-- TOC-START -->
-## Contents
-
-- [RESTe - API integration](#reste---api-integration)
-- [Camera app tutorial](#camera-app-tutorial)
-- [Geolocation tutorial](#geolocation-tutorial)
-- [Alloy controller chaining](#alloy-controller-chaining)
-- [Build automation with Fastlane](#build-automation-with-fastlane)
-- [Additional tutorials](#additional-tutorials)
-- [Resources](#resources-1)
-
-<!-- TOC-END -->
-
-## 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