@maccesar/titools 5.3.0 → 5.4.0

package/skills/ti-guides/references/advanced-data-and-images.md

@@ -1,155 +1,151 @@
-# Advanced database and image best practices
+# Working with data
 
-## 1. SQLite optimization
 
-- Close result sets and the database after each operation to avoid locks and memory growth. SQLite allows one writer at a time, and leaving a connection open after `INSERT` or `UPDATE` can trigger `DatabaseObjectNotClosed` on the next write.
-- Use transactions for batch inserts. If any statement fails, SQLite rolls back the entire batch.
-  ```javascript
-  const db = Ti.Database.open('myDatabase');
-  db.execute('BEGIN');
-  for (const item of playlist) {
-    db.execute('INSERT INTO albums (disc, artist, rating) VALUES (?, ?, ?)', item.disc, item.artist, item.rating);
-  }
-  db.execute('COMMIT');
-  db.close();
-  ```
-- Do not ship large pre-populated databases. Ship a small skeleton and download data on first boot to reduce IPA/APK size. The `Resources` directory is read-only, so installing a database copies it to `applicationDataDirectory`, which creates two copies on the device.
-  - Android note: in Android 2.2 and earlier, the installer could not uncompress assets over 1 MB. One workaround was to rename the file with a `.mp3` extension to prevent `aapt` compression.
-  - Pattern for downloading a replacement database on first boot:
-  ```javascript
-  const updateDatabase = (newData) => {
-    // delete existing content and rehydrate from downloaded JSON
-  }
-  downloadButton.addEventListener('click', () => {
-    const client = Ti.Network.createHTTPClient({
-      timeout: 10000,
-      onload() {
-        updateDatabase(this.responseData)
-        Ti.UI.createAlertDialog({ title: 'Info', message: 'Database installed' }).show()
-      },
-      onerror(e) {
-        Ti.UI.createAlertDialog({ title: 'Error', message: e.error }).show()
-      }
-    })
-    client.open('GET', 'https://example.com/data.json')
-    client.send()
-  })
-  ```
-
-### Database version management
-
-Store a version number in your database so you can detect upgrades and run migrations. If you do not have a version table, use `PRAGMA TABLE_INFO` to detect column presence:
+Titanium gives you three places to keep data on the device, and the whole
+decision is how much of it there is and what shape it has.
 
-```javascript
-const addColumn = (dbname, tblName, newFieldName, colSpec) => {
-  const db = Ti.Database.open(dbname);
-  let fieldExists = false;
-  const resultSet = db.execute(`PRAGMA TABLE_INFO(${tblName})`);
-  while (resultSet.isValidRow()) {
-    if (resultSet.field(1) === newFieldName) {
-      fieldExists = true;
-    }
-    resultSet.next();
-  }
-  resultSet.close();
-  if (!fieldExists) {
-    db.execute(`ALTER TABLE ${tblName} ADD COLUMN ${newFieldName} ${colSpec}`);
-  }
-  db.close();
-};
+| Store | For | Survives an uninstall |
+| ----- | --- | --------------------- |
+| `Ti.App.Properties` | Settings and small values | No |
+| `Ti.Filesystem` | Files, downloads, generated content | No |
+| `Ti.Database` | Rows you query | No |
+
+None of them survive an uninstall. Anything that must is on a server, and
+[networking](https://titaniumsdk.com/docs/build/data/networking) is how it gets there.
+
+## Properties
+
+Key-value storage for small things: the last tab, whether the user has
+seen the tour. It is backed by `NSUserDefaults` on iOS and `SharedPreferences`
+on Android, and it is read synchronously.
+
+```js
+Ti.App.Properties.setString('lastTab', 'inbox');
+Ti.App.Properties.setBool('seenTour', true);
+
+const tab = Ti.App.Properties.getString('lastTab', 'inbox');
+const seen = Ti.App.Properties.getBool('seenTour', false);
 ```
 
----
+Every getter takes a default as its second argument. Use it rather than
+checking `hasProperty` first, which is a second lookup for the same answer.
+
+There is a setter and getter per type - `setString`, `setInt`, `setBool`,
+`setDouble`, `setList`, `setObject` - and reading with the wrong one does not
+convert. Store with `setInt` and read with `getString` and you get the default
+back.
 
-## 2. Image format selection
+`setObject` and `setList` serialise to JSON, so they are for a handful of
+values, not a collection you keep adding to.
 
-Choose the right format for each use case:
+> [!WARNING]
+> Properties are not secure storage. They are plain preferences, readable on a
+> rooted or jailbroken device and included in an unencrypted device backup. A
+> token you would mind losing belongs in the keychain or keystore, which is a
+> native module rather than a core API.
 
-| Format | Compression           | Best for                       | Avoid for                                                          |
-| ------ | --------------------- | ------------------------------ | ------------------------------------------------------------------ |
-| PNG    | Lossless              | Icons, text, line art, buttons | Photos (large files)                                               |
-| JPG    | Lossy                 | Photographs                    | Text, icons, line drawings (artifacts)                             |
-| GIF    | Lossless (256 colors) | Rare cases                     | Most cases (limited colors, animated GIF not supported everywhere) |
+## Files
 
-For flip-book animations, use `ImageView.images` with an array of PNG or optimized JPG files instead of animated GIFs.
+`Ti.Filesystem` addresses directories by purpose, and the purpose decides
+whether the operating system may delete what you put there.
 
----
+| Directory | Use for | Backed up |
+| --------- | ------- | --------- |
+| `applicationDataDirectory` | Content the app created and needs | Yes |
+| `applicationCacheDirectory` | Anything re-downloadable | No, and may be purged |
+| `tempDirectory` | Working files for right now | No |
+| `resourcesDirectory` | What you shipped. **Read-only** | n/a |
 
-## 3. Image memory management
+```js
+const file = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, 'notes.txt');
+file.write('written on ' + new Date().toISOString());
 
-- A JPG is small on disk but expands to `width * height * 3 bytes` in RAM. Each pixel uses 24 bits (8 bits per R/G/B channel).
-  - Example: `(640 × 480 × 3) / 1024 = 900 KB` in memory for a single image
-  - Device RAM available to your app can be as low as 12 MB, shared with your code and the Titanium framework
-- Unloading:
-  - `view.remove(imageView)` removes it from the view hierarchy and lets the OS free memory
-  - `imageView = null` releases the native proxy object
-- Resizing: resize images to their display dimensions using `imageAsResized` or `imageAsCropped` (both on `Ti.Blob`) before setting the `image` property. Do not display a 1024×768 image on a 640×480 screen.
-- Placeholder: set `defaultImage` on ImageView to show a local placeholder while a remote image downloads:
-  ```javascript
-  const imageView = Ti.UI.createImageView({
-    image: 'https://example.com/photo.jpg',
-    defaultImage: '/images/placeholder.png',
-    width: 300,
-    height: 200
-  });
-  ```
+if (file.exists()) {
+  Ti.API.info(file.read().text);
+}
+```
+
+`getFile` takes path segments and joins them, so pass the directory and the
+name rather than concatenating with a separator yourself.
+
+Putting a cache in `applicationDataDirectory` is the common mistake: it is
+backed up, so a 200MB image cache goes into the user's iCloud backup.
+
+## A database
+
+`Ti.Database` is SQLite. Open a database by name and it is created on first
+use.
+
+```js
+const db = Ti.Database.open('notes');
 
----
+db.execute(`
+  CREATE TABLE IF NOT EXISTS notes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    body TEXT NOT NULL,
+    created TEXT NOT NULL
+  )
+`);
 
-## 4. Image optimization tools
+db.execute('INSERT INTO notes (body, created) VALUES (?, ?)', 'First note', new Date().toISOString());
+Ti.API.info(`inserted row ${db.lastInsertRowId}`);
 
-Resize and compress images before including them in your app to reduce IPA/APK size and network usage.
+const rows = db.execute('SELECT id, body FROM notes ORDER BY id DESC');
+while (rows.isValidRow()) {
+  Ti.API.info(`${rows.fieldByName('id')}: ${rows.fieldByName('body')}`);
+  rows.next();
+}
+rows.close();
+db.close();
+```
+
+**Pass values as arguments, never by building the SQL string.** The `?`
+placeholders are escaped for you; string concatenation is how an apostrophe in
+a note becomes a syntax error and how a hostile value becomes an injection.
+
+A result set is a cursor, not an array: walk it with `isValidRow()` and
+`next()`, and close it. Close the database when you are done with it.
 
-| Platform            | File types    | Tool        |
-| ------------------- | ------------- | ----------- |
-| Mac                 | PNG, JPG, GIF | ImageOptim  |
-| Mac, Windows, Linux | PNG, JPG, GIF | ImageMagick |
-| Windows/DOS         | PNG           | PNGCrush    |
-| Windows             | JPG           | Nikkho      |
+`executeAsync` and `executeAllAsync` run off the main thread and take a
+callback. Use them for anything large enough to be noticeable, which on a
+phone is sooner than you would guess.
 
----
+### Shipping a prepared database
 
-## 5. Caching remote images
+`Ti.Database.install` copies a `.sqlite` file out of your resources on first
+run and opens it, so an app can ship with data already in it.
 
-Remote images are cached automatically on iOS, Android, and Windows.
+```js
+const db = Ti.Database.install('/data/seed.sqlite', 'notes');
+```
 
-Platform differences:
-- Android: cache limited to 25 MB, persists for the lifetime of the app (while installed)
-- iOS: cache size not fixed, cleared by iOS when the device needs storage
+The copy happens once. Changing the shipped file in a later release does not
+replace a database the user already has, so version your schema and migrate.
 
-To manually clean the cache, delete files in `applicationCacheDirectory`.
+## Next
 
-Android 6+ requirement: call `Ti.Filesystem.requestStoragePermissions()` before loading remote images.
+[Networking and remote data](https://titaniumsdk.com/docs/build/data/networking) is the other half:
+getting data in and out over HTTP.
 
-### Manual caching utility
+## Close resources on failures
 
-For critical assets, cache manually in `applicationDataDirectory` for more predictable behavior:
+The cursor and database cleanup in the straight-line example must also run when query execution or processing throws. Put cursor cleanup in `finally`, then close the database. `executeAsync` and `executeAllAsync` also return Promises on SDK 10+; await completion before closing handles, and close every returned cursor, including partial results reported by a failed batch.
 
 ```javascript
-const CacheUtils = {
-  getExtension: (fn) => {
-    const match = /(?:\.([^.]+))?$/.exec(fn);
-    return match[1] || '';
-  },
-
-  createCachedImageView: (options) => {
-    const md5 = Ti.Utils.md5HexDigest(options.image) + CacheUtils.getExtension(options.image);
-    const savedFile = Ti.Filesystem.getFile(Ti.Filesystem.applicationDataDirectory, md5);
-
-    if (savedFile.exists()) {
-      options.image = savedFile;
-      return Ti.UI.createImageView(options);
+async function readNotes() {
+  const db = Ti.Database.open('notes');
+  let rows;
+  try {
+    rows = await db.executeAsync('SELECT id, body FROM notes ORDER BY id DESC');
+    while (rows.isValidRow()) {
+      Ti.API.info(rows.fieldByName('body'));
+      rows.next();
     }
-
-    const imageView = Ti.UI.createImageView(options);
-    const saveImage = () => {
-      imageView.removeEventListener('load', saveImage);
-      savedFile.write(
-        Ti.UI.createImageView({ image: imageView.image, width: Ti.UI.FILL, height: Ti.UI.FILL }).toImage()
-      );
-    };
-    imageView.addEventListener('load', saveImage);
-    return imageView;
+  } finally {
+    if (rows) {
+      rows.close();
+    }
+    db.close();
   }
-};
+}
 ```

package/skills/ti-guides/references/android-manifest.md

@@ -1,97 +1,38 @@
-# Custom AndroidManifest.xml
+# Android manifest configuration
 
-For most Android manifest settings, use `tiapp.xml`. Only create a custom manifest when you really need it.
+## Android
 
-## Preferred method: tiapp.xml
+Children of `<android>`. As with `<ios>`, anything else is discarded. The
+`xmlns:android` declaration belongs on the `<android>` element.
 
-Add manifest entries in `tiapp.xml` inside the `<android>` section:
+| Element          | Value           | Effect                                                              |
+| ---------------- | --------------- | ------------------------------------------------------------------- |
+| `manifest`       | XML             | Merged into the generated `AndroidManifest.xml`                     |
+| `tool-api-level` | int             | The API level the app is compiled against                           |
+| `abi`            | comma-separated | Which ABIs to package. `all` packages every one                     |
+| `activities`     | element         | Extra activities, each keyed by the JavaScript file it opens        |
+| `services`       | element         | Extra services. `type="quicksettings"` builds a quick settings tile |
 
 ```xml
 <android xmlns:android="http://schemas.android.com/apk/res/android">
-    <manifest>
-        <!-- SDK version -->
-        <uses-sdk android:minSdkVersion="21" android:targetSdkVersion="34" />
-
-        <!-- Screen support -->
-        <supports-screens
-            android:smallScreens="false"
-            android:normalScreens="true"
-            android:largeScreens="true"
-            android:xlargeScreens="true"
-        />
-
-        <!-- Permissions -->
-        <uses-permission android:name="android.permission.CAMERA" />
-        <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
-
-        <!-- Application attributes (merged, not replaced) -->
-        <application android:debuggable="true" />
-    </manifest>
+  <manifest android:versionCode="1">
+    <uses-permission android:name="android.permission.CAMERA"/>
+    <application android:icon="@mipmap/ic_launcher"/>
+  </manifest>
+  <abi>arm64-v8a,x86_64</abi>
 </android>
 ```
 
-## How merging works
-
-- Most elements are replaced by your entry.
-- The `<application>` element is merged additively by attribute.
-- Activities and services are added to existing ones.
-
-## Custom manifest (rare cases)
-
-If you need full control, create `platform/android/AndroidManifest.xml`:
-
-```
-MyApp/
-├── app/
-├── platform/
-│   └── android/
-│       └── AndroidManifest.xml  # Custom manifest
-└── tiapp.xml
-```
-
-Warning: you must maintain this file manually through SDK updates.
-
-## Common use cases
-
-### Camera permission
-```xml
-<uses-permission android:name="android.permission.CAMERA" />
-```
-
-### Hardware requirements
-```xml
-<uses-feature android:name="android.hardware.camera" android:required="false" />
-```
+`android:versionCode` is the integer Google Play orders releases by, and it has
+to increase on every upload. `<version>` above is the human one; these are
+separate numbers and both matter.
 
-### Launch mode
-```xml
-<application android:launchMode="singleTask" />
-```
+Restricting `abi` shrinks the APK and is the usual reason to set it. An ABI you
+drop is a device the app will not install on.
 
-### Deep links
-```xml
-<intent-filter>
-    <action android:name="android.intent.action.VIEW" />
-    <category android:name="android.intent.category.DEFAULT" />
-    <category android:name="android.intent.category.BROWSABLE" />
-    <data android:scheme="myapp" android:host="path" />
-</intent-filter>
-```
-
-## Debugging
-
-To see the generated manifest:
-```bash
-ti build -p android
-# Check: build/android/AndroidManifest.xml.gen
-```
-
-## Enable manifest merge (CLI 7.0+)
 
-If you use a custom manifest, enable merge in `tiapp.xml`:
+## Merge and inspect the release variant
 
-```bash
-ti config android.mergeCustomAndroidManifest true
-```
+SDK 13.4.1 generates a base `src/main/AndroidManifest.xml` plus variant overlays below `build/android/`; Gradle merges app, library and module manifests. Use Android manifest-merger rules and `tools:remove` when needed, then inspect the actual merged release manifest. The legacy `android.mergeCustomAndroidManifest=false` switch is unsupported and does not restore replacement mode. A declared permission still needs its runtime permission workflow where the OS requires it.
 
-This merges your custom manifest with the generated one instead of replacing it.
+`<tool-api-level>` is the compile API. Manifest min/target APIs are different settings; use the released [compatibility baseline](compatibility-matrix.md). Do not force debuggable in distributed artifacts. For other XML elements see [tiapp.xml](tiapp-config.md).