@maccesar/titools 2.0.0

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

@@ -0,0 +1,301 @@
+# Local Data Sources
+
+## Table of Contents
+
+- [Local Data Sources](#local-data-sources)
+  - [Table of Contents](#table-of-contents)
+  - [1. Filesystem Access and Storage](#1-filesystem-access-and-storage)
+    - [Modules Overview](#modules-overview)
+    - [Storage Locations](#storage-locations)
+    - [File Operations](#file-operations)
+      - [Getting a File Handle](#getting-a-file-handle)
+      - [Writing Files](#writing-files)
+      - [Reading Files](#reading-files)
+      - [Appending](#appending)
+      - [Creating/Copying](#creatingcopying)
+      - [Renaming](#renaming)
+      - [Deleting](#deleting)
+    - [Directory Operations](#directory-operations)
+    - [Case Sensitivity Warning](#case-sensitivity-warning)
+  - [2. SQLite Database](#2-sqlite-database)
+    - [Opening Databases](#opening-databases)
+    - [Querying Data](#querying-data)
+    - [Parameterized Queries](#parameterized-queries)
+    - [Data Modification](#data-modification)
+    - [**CRITICAL**: Always Close Connections](#critical-always-close-connections)
+  - [3. Properties API (Ti.App.Properties)](#3-properties-api-tiappproperties)
+    - [Overview](#overview)
+    - [Data Type Methods](#data-type-methods)
+    - [Usage Examples](#usage-examples)
+    - [Storing Complex Objects as JSON](#storing-complex-objects-as-json)
+    - [Platform Storage](#platform-storage)
+  - [4. Advanced Data Manipulation (Buffer, Codec, and Streams)](#4-advanced-data-manipulation-buffer-codec-and-streams)
+  - [5. Choosing a Persistence Strategy](#5-choosing-a-persistence-strategy)
+    - [Decision Guide](#decision-guide)
+    - [Best Practices](#best-practices)
+
+---
+
+## 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 interface
+
+### 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**: File handle still points to 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: **lowercase all file names**.
+
+## 2. SQLite 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();
+}
+
+// **CRITICAL**: 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;  // Get inserted ID
+
+// UPDATE
+db.execute('UPDATE users SET age = ? WHERE name = ?', [31, 'Jane']);
+const rowsAffected = db.rowsAffected;
+
+// DELETE
+db.execute('DELETE FROM users WHERE age < ?', [18]);
+```
+
+### **CRITICAL**: 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**: 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 `.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, refer to the detailed guide:
+
+- [Buffer, Codec, and Streams](./buffer-codec-streams.md): Using `Ti.Buffer`, `Ti.Codec` for numbers/strings, and efficient chunk-based reading.
+
+## 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; don't let them accumulate

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

@@ -0,0 +1,252 @@
+# Location Services and Maps
+
+## Table of Contents
+
+- [Location Services and Maps](#location-services-and-maps)
+  - [Table of Contents](#table-of-contents)
+  - [1. GPS Position Tracking](#1-gps-position-tracking)
+    - [FusedLocationProvider (Android)](#fusedlocationprovider-android)
+    - [Accuracy Configuration](#accuracy-configuration)
+    - [Android Configuration Modes](#android-configuration-modes)
+    - [One-Time Position](#one-time-position)
+    - [Continuous Monitoring](#continuous-monitoring)
+    - [Lifecycle Management (Critical for Battery)](#lifecycle-management-critical-for-battery)
+    - [Compass/Heading](#compassheading)
+  - [Geocoding](#geocoding)
+    - [Forward Geocoding (Address → Coordinates)](#forward-geocoding-address--coordinates)
+    - [Reverse Geocoding (Coordinates → Places)](#reverse-geocoding-coordinates--places)
+  - [2. Native Maps (Platform-Specific Details)](#2-native-maps-platform-specific-details)
+  - [Common Map Patterns](#common-map-patterns)
+    - [Add Annotation After Map Creation](#add-annotation-after-map-creation)
+    - [Remove Annotation](#remove-annotation)
+    - [Remove All Annotations](#remove-all-annotations)
+    - [Select Annotation Programmatically](#select-annotation-programmatically)
+    - [Deselect Annotation](#deselect-annotation)
+    - [Set Region with Animation](#set-region-with-animation)
+    - [Zoom to Annotations](#zoom-to-annotations)
+    - [Best Practices](#best-practices)
+
+---
+
+## 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
+```
+
+### 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;
+```
+
+### 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}`);
+    }
+});
+```
+
+---
+
+## 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}`);
+    }
+});
+```
+
+### 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): API Keys configuration, Google Play Services, and advanced controls.
+- [iOS Map Kit](./ios-map-kit.md): 3D Camera, system buttons, and Info.plist configuration.
+
+---
+
+## 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**: Always 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 module for multiple views.
+5. **API Keys**: Google Maps API key required for Android (both debug and production).
+6. **User Location**: Requires location permissions (`NSLocationWhenInUseUsageDescription` for iOS).