@maccesar/titools 3.2.0 → 4.0.0

package/skills/ti-howtos/references/local-data-sources.md

@@ -0,0 +1,310 @@
+# Local data sources
+
+## 1. Filesystem access and storage
+
+### Modules overview
+- `Ti.Filesystem` - top-level module for file/directory operations
+- `Ti.Filesystem.File` - file object with read/write methods
+- `Ti.Filesystem.FileStream` - stream wrapper implementing `Ti.IOStream`
+
+### Storage locations
+
+| Location                    | Read/Write | Persistence      | Notes                                  |
+| --------------------------- | ---------- | ---------------- | -------------------------------------- |
+| `applicationDataDirectory`  | R/W        | Until uninstall  | Primary app data location              |
+| `resourcesDirectory`        | R-only     | Until uninstall  | App resources (R/W in simulator only)  |
+| `tempDirectory`             | R/W        | Until app closes | OS may delete anytime                  |
+| `applicationCacheDirectory` | R/W        | OS may clean     | For cached data                        |
+| `externalCacheDirectory`    | R/W        | OS may clean     | Android SD card cache                  |
+| `externalStorageDirectory`  | R/W        | Until uninstall  | Android SD card storage                |
+
+Always check `Ti.Filesystem.isExternalStoragePresent()` before using external storage on Android.
+
+### File operations
+
+#### Getting a file handle
+```javascript
+const f = Ti.Filesystem.getFile(
+  Ti.Filesystem.applicationDataDirectory,
+  'myfile.txt'
+);
+```
+
+#### Writing files
+```javascript
+f.write('Content here'); // Overwrites or creates
+```
+
+#### Reading files
+```javascript
+const contents = f.read(); // Returns Blob
+Ti.API.info(contents.text); // Text content
+Ti.API.info(contents.mimeType); // MIME type
+```
+
+#### Appending
+```javascript
+f.append('More content\n'); // String, Blob, or File
+```
+
+#### Creating/copying
+```javascript
+// Auto-creates on write, but explicit option exists:
+if (!f.exists()) {
+  f.createFile();
+}
+
+// Android copy method:
+const oldFile = Ti.Filesystem.getFile(applicationDataDirectory, 'old.txt');
+oldFile.copy(`${applicationDataDirectory}new.txt`);
+
+// iOS (no copy method):
+const newFile = Ti.Filesystem.getFile(applicationDataDirectory, 'new.txt');
+newFile.write(oldFile.read());
+```
+
+#### Renaming
+Important: the file handle still points to the old name after rename.
+
+```javascript
+const f = Ti.Filesystem.getFile(applicationDataDirectory, 'old.txt');
+f.rename('new.txt');
+// f still references 'old.txt' (now non-existent)
+const newf = Ti.Filesystem.getFile(applicationDataDirectory, 'new.txt');
+```
+
+#### Deleting
+```javascript
+if (f.exists() && f.writable) {
+  const success = f.deleteFile(); // Returns Boolean, no error thrown
+}
+```
+
+### Directory operations
+
+```javascript
+// Create directory
+const dir = Ti.Filesystem.getFile(applicationDataDirectory, 'mysubdir');
+dir.createDirectory();
+
+// List contents
+const listing = dir.getDirectoryListing();
+
+// Move file into directory
+const file = Ti.Filesystem.getFile(applicationDataDirectory, 'file.txt');
+file.move('mysubdir/file.txt');
+
+// Delete directory (must be empty or force recursive)
+dir.deleteDirectory(false); // Fails if not empty
+dir.deleteDirectory(true); // Recursive delete
+```
+
+### Case sensitivity warning
+Android and Mobile Web use case-sensitive filesystems. File names referenced in code must match actual file names exactly. Recommendation: use lowercase file names.
+
+## 2. SQLite database
+
+### Installing a pre-populated database
+Ship a database with your app and install it on first launch:
+```javascript
+// Copies db from Resources/ (or app/assets/) to applicationDataDirectory
+const db = Ti.Database.install('seeds/mydata.sqlite', 'mydata');
+// On subsequent launches, install() just opens the existing database
+```
+
+### Opening databases
+
+```javascript
+// Install (copies from Resources if first time)
+const db = Ti.Database.install('mydb.sqlite', 'myInstalledDB');
+
+// Or open existing database in applicationDataDirectory
+const db = Ti.Database.open('myDatabase');
+
+// For app data directory location:
+const dbFile = Ti.Filesystem.getFile(
+  Ti.Filesystem.applicationDataDirectory,
+  'mydb.sqlite'
+);
+const db = Ti.Database.open(dbFile.nativePath);
+```
+
+### Querying data
+
+```javascript
+const rows = db.execute('SELECT * FROM users WHERE age > ?', [18]);
+
+while (rows.isValidRow()) {
+  Ti.API.info(rows.fieldByName('name'));
+  Ti.API.info(rows.field(0)); // First column by index
+  rows.next();
+}
+
+// Always close result set
+rows.close();
+```
+
+### Parameterized queries
+Always use parameters to prevent SQL injection:
+
+```javascript
+// Safe - parameterized
+db.execute('INSERT INTO users (name, age) VALUES (?, ?)', ['John', 25]);
+
+// Unsafe - never do this
+db.execute(`INSERT INTO users (name, age) VALUES ('${name}', ${age})`);
+```
+
+### Data modification
+
+```javascript
+// INSERT
+db.execute('INSERT INTO users (name, age) VALUES (?, ?)', ['Jane', 30]);
+const lastId = db.lastInsertRowId; // ID of the last inserted row
+const affected = db.rowsAffected; // number of rows changed by last statement
+
+// UPDATE
+db.execute('UPDATE users SET age = ? WHERE name = ?', [31, 'Jane']);
+const rowsAffected = db.rowsAffected;
+
+// DELETE
+db.execute('DELETE FROM users WHERE age < ?', [18]);
+```
+
+### Transactions for batch operations
+Use transactions to speed up multiple inserts or updates:
+```javascript
+const db = Ti.Database.open('mydb');
+db.execute('BEGIN');
+try {
+  for (let i = 0; i < items.length; i++) {
+    db.execute('INSERT INTO products (name, price) VALUES (?, ?)', items[i].name, items[i].price);
+  }
+  db.execute('COMMIT');
+} catch (e) {
+  db.execute('ROLLBACK');
+  Ti.API.error(`Transaction failed: ${e.message}`);
+}
+db.close();
+```
+
+Performance: wrapping 1000 inserts in a transaction can be 10-100x faster than individual inserts.
+
+### SQLite limitations
+- No `FULL OUTER JOIN` support. Use `LEFT JOIN` with `UNION`.
+- Limited `ALTER TABLE`. You can only `ADD COLUMN` or `RENAME TABLE`.
+- No built-in referential integrity (foreign keys). Enable with `PRAGMA foreign_keys = ON`.
+- No native boolean type. Use INTEGER (0/1).
+
+### Disable iCloud backup for databases (iOS)
+
+iOS backs up databases to iCloud by default. For large or recreatable databases, disable this:
+```javascript
+const db = Ti.Database.open('mydb');
+db.file.setRemoteBackup(false);
+db.close();
+```
+
+Important: Apple may reject apps that back up large recreatable data to iCloud.
+
+### Always close connections
+
+```javascript
+try {
+  // Database operations
+} finally {
+  // Always close, even on error
+  if (rows) rows.close();
+  if (db) db.close();
+}
+```
+
+## 3. Properties API (Ti.App.Properties)
+
+### Overview
+Lightweight key-value storage for simple data types. Loaded into memory at launch for fast access.
+
+Warning: there is no hard limit, but all properties load into memory. Avoid storing large data.
+
+### Data type methods
+
+| Type   | Get method                 | Set method               |
+| ------ | -------------------------- | ------------------------ |
+| String | `getString(name, default)` | `setString(name, value)` |
+| Int    | `getInt(name, default)`    | `setInt(name, value)`    |
+| Double | `getDouble(name, default)` | `setDouble(name, value)` |
+| Bool   | `getBool(name, default)`   | `setBool(name, value)`   |
+| List   | `getList(name, default)`   | `setList(name, value)`   |
+
+### Usage examples
+
+```javascript
+// Set values
+Ti.App.Properties.setString('username', 'john');
+Ti.App.Properties.setInt('loginCount', 5);
+Ti.App.Properties.setBool('isLoggedIn', true);
+Ti.App.Properties.setDouble('price', 19.99);
+Ti.App.Properties.setList('favorites', ['item1', 'item2']);
+
+// Get values (with defaults)
+const username = Ti.App.Properties.getString('username', 'guest');
+const count = Ti.App.Properties.getInt('loginCount', 0);
+
+// Check if property exists
+if (Ti.App.Properties.hasProperty('username')) {
+  // ...
+}
+
+// Remove property
+Ti.App.Properties.removeProperty('username');
+
+// List all properties
+const allProps = Ti.App.Properties.listProperties();
+```
+
+### Storing complex objects as JSON
+
+```javascript
+// Store object as JSON string
+const data = { city: 'Mountain View', temp: 72 };
+Ti.App.Properties.setString('weatherData', JSON.stringify(data));
+
+// Retrieve and parse
+const stored = Ti.App.Properties.getString('weatherData', '{}');
+const weather = JSON.parse(stored);
+Ti.API.info(weather.city); // 'Mountain View'
+```
+
+### Platform storage
+- iOS: `NSUserDefaults` in a `.plist` file
+- Android: XML file at `/data/data/com.domain.app/shared_prefs/titanium.xml`
+
+## 4. Advanced data manipulation (Buffer, Codec, and Streams)
+
+For binary data handling, character encoding, and large file streams, see:
+
+- Buffer, Codec, and Streams: `buffer-codec-streams.md`
+
+## 5. Choosing a persistence strategy
+
+### Decision guide
+
+| Scenario                           | Recommended approach                     |
+| ---------------------------------- | ---------------------------------------- |
+| User settings/preferences          | `Ti.App.Properties`                      |
+| Small config data (< 100KB)        | `Ti.App.Properties` with JSON            |
+| Structured relational data         | SQLite                                   |
+| Large binary data (images, videos) | Filesystem                               |
+| Downloaded content cache           | Filesystem (`applicationCacheDirectory`) |
+| Temporary processing data          | Filesystem (`tempDirectory`)             |
+| User-generated files               | Filesystem (`applicationDataDirectory`)  |
+| Offline-first app data             | SQLite + Filesystem combo                |
+
+### Best practices
+
+1. Properties API: use only for small, frequently accessed config data.
+2. SQLite: always close connections and result sets; use parameterized queries.
+3. Filesystem: check external storage availability on Android; handle case sensitivity.
+4. Streams: use for large file operations to avoid memory issues.
+5. Hybrid approach: store metadata in SQLite, file paths in records, actual files on filesystem.
+6. Cleanup: implement cleanup for temp files and cache; do not let them accumulate.

package/skills/ti-howtos/references/location-and-maps.md

@@ -0,0 +1,267 @@
+# Location services and maps
+
+## 1. GPS position tracking
+
+### FusedLocationProvider (Android)
+Since TiSDK 7.1.0, Titanium supports `FusedLocationProvider` for significant battery savings.
+Requirement: include the `ti.playservices` module in your project.
+
+### Accuracy configuration
+
+iOS accuracy levels:
+- `ACCURACY_BEST` - highest power (GPS)
+- `ACCURACY_NEAREST_TEN_METERS` - medium-high power
+- `ACCURACY_HUNDRED_METERS` - medium power
+- `ACCURACY_KILOMETER` - low power
+- `ACCURACY_THREE_KILOMETERS` - lowest power (cell/wifi)
+
+Key properties:
+```javascript
+Ti.Geolocation.accuracy = Ti.Geolocation.ACCURACY_BEST;
+Ti.Geolocation.distanceFilter = 10; // meters - only fire if moved X meters
+Ti.Geolocation.headingFilter = 5; // degrees - only fire if heading changed X degrees
+Ti.Geolocation.preferredProvider = Ti.Geolocation.PROVIDER_GPS; // or PROVIDER_NETWORK
+```
+
+Note: on many Android devices, a low-precision passive location provider is always enabled, even when the user disables GPS and Network providers. `Ti.Geolocation.locationServicesEnabled` may always return `true` on those devices.
+
+### Android configuration modes
+
+Simple mode (ACCURACY_HIGH/LOW):
+```javascript
+Ti.Geolocation.accuracy = Ti.Geolocation.ACCURACY_HIGH;
+```
+
+Manual mode (fine-grained control):
+```javascript
+const providerGps = Ti.Geolocation.Android.createLocationProvider({
+  name: Ti.Geolocation.PROVIDER_GPS,
+  minUpdateDistance: 0.0,
+  minUpdateTime: 0
+});
+Ti.Geolocation.Android.addLocationProvider(providerGps);
+Ti.Geolocation.Android.manualMode = true;
+```
+
+### Location permissions
+
+```javascript
+// Check permissions
+if (Ti.Geolocation.hasLocationPermissions(Ti.Geolocation.AUTHORIZATION_WHEN_IN_USE)) {
+  startTracking();
+} else {
+  Ti.Geolocation.requestLocationPermissions(Ti.Geolocation.AUTHORIZATION_WHEN_IN_USE, (e) => {
+    if (e.success) {
+      startTracking();
+    } else {
+      Ti.API.error(`Permission denied: ${e.error}`);
+    }
+  });
+}
+```
+
+iOS plist keys (tiapp.xml):
+```xml
+<key>NSLocationWhenInUseUsageDescription</key>
+<string>We need your location to show nearby places</string>
+<!-- For background location: -->
+<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
+<string>We need background location for navigation</string>
+```
+
+Note (iOS 11+): you must include `NSLocationAlwaysAndWhenInUseUsageDescription` even when requesting "Always" permission. Users can still choose "When in Use".
+
+### One-time position
+
+```javascript
+if (Ti.Geolocation.locationServicesEnabled) {
+  Ti.Geolocation.getCurrentPosition((e) => {
+    if (e.error) {
+      Ti.API.error(`Error: ${e.error}`);
+    } else {
+      const coords = e.coords;
+      // { latitude, longitude, altitude, accuracy, heading, speed, timestamp }
+    }
+  });
+}
+```
+
+### Continuous monitoring
+
+```javascript
+Ti.Geolocation.addEventListener('location', (e) => {
+  if (e.error) {
+    Ti.API.error(`Error: ${e.error}`);
+  } else {
+    Ti.API.info(`${e.coords.latitude}, ${e.coords.longitude}`);
+  }
+});
+```
+
+### Lifecycle management (critical for battery)
+
+Android Activity events:
+```javascript
+let locationAdded = false;
+const handleLocation = (e) => {
+  if (!e.error) {
+    Ti.API.info(e.coords);
+  }
+};
+
+function addHandler() {
+  if (!locationAdded) {
+    Ti.Geolocation.addEventListener('location', handleLocation);
+    locationAdded = true;
+  }
+}
+
+function removeHandler() {
+  if (locationAdded) {
+    Ti.Geolocation.removeEventListener('location', handleLocation);
+    locationAdded = false;
+  }
+}
+
+// Add listeners
+addHandler();
+
+const activity = Ti.Android.currentActivity;
+activity.addEventListener('destroy', removeHandler);
+activity.addEventListener('pause', removeHandler); // Stop when in background
+activity.addEventListener('resume', addHandler); // Resume when foreground
+```
+
+### Compass/heading
+
+```javascript
+// One-time heading
+Ti.Geolocation.getCurrentHeading((e) => {
+  Ti.API.info(e.heading.magneticHeading); // degrees from magnetic north
+  Ti.API.info(e.heading.trueHeading); // degrees from true north
+});
+
+// Continuous heading monitoring
+Ti.Geolocation.addEventListener('heading', (e) => {
+  if (!e.error) {
+    Ti.API.info(`Heading: ${e.heading.magneticHeading}`);
+  }
+});
+```
+
+The heading event object includes:
+- `heading.magneticHeading` - degrees relative to magnetic north
+- `heading.trueHeading` - degrees relative to true north (requires location)
+- `heading.accuracy` - deviation in degrees (lower is better)
+- `heading.x`, `heading.y`, `heading.z` - raw magnetometer data (microteslas)
+
+## Geocoding
+
+### Forward geocoding (address → coordinates)
+
+```javascript
+Ti.Geolocation.forwardGeocoder('440 Bernardo Ave Mountain View CA', (e) => {
+  if (e.success) {
+    Ti.API.info(`Lat: ${e.latitude}, Lon: ${e.longitude}`);
+  }
+});
+```
+
+With error handling:
+```javascript
+Ti.Geolocation.forwardGeocoder('1600 Amphitheatre Pkwy, Mountain View, CA', (e) => {
+  if (!e.success || e.error) {
+    Ti.API.error(`Geocoding failed: ${e.error}`);
+    return;
+  }
+  Ti.API.info(`Lat: ${e.latitude}, Lng: ${e.longitude}`);
+});
+```
+
+### Reverse geocoding (coordinates → places)
+
+```javascript
+Ti.Geolocation.reverseGeocoder(37.389569, -122.050212, (e) => {
+  if (e.success) {
+    e.places.forEach((place) => {
+      Ti.API.info(place.address); // Full address
+      Ti.API.info(place.city); // City name
+      Ti.API.info(place.country); // Country
+      Ti.API.info(place.zipcode); // Postal code
+    });
+  }
+});
+```
+
+## 2. Native maps (platform-specific details)
+
+Due to the complexity of modern native maps, refer to the detailed guides:
+
+- Google Maps v2 for Android: `google-maps-v2.md`
+- iOS Map Kit: `ios-map-kit.md`
+
+## Common map patterns
+
+### Add annotation after map creation
+
+```javascript
+mapview.addAnnotation(annotation);
+```
+
+### Remove annotation
+
+```javascript
+mapview.removeAnnotation(annotation);
+```
+
+### Remove all annotations
+
+```javascript
+mapview.removeAllAnnotations();
+```
+
+### Select annotation programmatically
+
+```javascript
+mapview.selectAnnotation(annotation);
+```
+
+### Deselect annotation
+
+```javascript
+mapview.deselectAnnotation(annotation);
+```
+
+### Set region with animation
+
+```javascript
+mapview.setLocation({
+  latitude: 37.389569,
+  longitude: -122.050212,
+  animate: true
+});
+
+// Or for region
+mapview.setRegion({
+  latitude: 37.389569,
+  longitude: -122.050212,
+  latitudeDelta: 0.05,
+  longitudeDelta: 0.05,
+  animate: true
+});
+```
+
+### Zoom to annotations
+
+```javascript
+mapview.showAnnotations([annotation1, annotation2], true); // true = animate
+```
+
+### Best practices
+
+1. Battery life: remove location listeners when not needed. Use `distanceFilter` to reduce updates.
+2. Accuracy: use the lowest accuracy that meets your needs.
+3. Permissions: check permissions before requesting location. Handle denial gracefully.
+4. Maps on Android: only one map view per application (legacy). Use `ti.map` for multiple views.
+5. API keys: Google Maps API key required for Android (debug and production).
+6. User location: requires location permissions (`NSLocationWhenInUseUsageDescription` for iOS).