From e8f2e264427b74c043c4a4351c4720035f20d5e5 Mon Sep 17 00:00:00 2001 From: "Christopher J. Brody" Date: Fri, 29 Jun 2018 15:21:31 -0400 Subject: [PATCH] Move & update existing browser platform notes ref: - litehelpers/Cordova-sqlite-storage#297 - litehelpers/Cordova-sqlite-storage#576 - litehelpers/Cordova-sqlite-help#8 --- README.md | 55 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 6dccd24fd..240aff479 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Native SQLite component with API based on HTML5/[Web SQL (DRAFT) API](http://www - macOS ("osx" platform) - Windows 10 (UWP) DESKTOP and MOBILE (see below for major limitations) -Browser platform is supported _with some limitations (no support for numbered parameters)_ as described in [Browser platform usage notes](#browser-platform-usage-notes) section below. +Browser platform is currently supported with some limitations as described in [browser platform usage notes](#browser-platform-usage-notes) section below, will be supported with more features such as numbered parameters in upcoming major release for July 2018 (see below). **LICENSE:** MIT, with Apache 2.0 option for Android and Windows platforms (see [LICENSE.md](./LICENSE.md) for details, including third-party components used by this plugin) @@ -29,13 +29,6 @@ New release in July 2018 will include the following major enhancements ([litehel - ~~drop Android NDK build for x86_64 ([litehelpers/Cordova-sqlite-storage#772](https://github.com/litehelpers/Cordova-sqlite-storage/issues/772)); NDK build for x86 will still work on x86_64 if no other plugins have NDK build for x86_64; feedback is requested in case of interest in NDK build for x86_64~~ - drop support for location: 0-2 values in openDatabase call (please use `location: 'default'` or `iosDatabaseLocation` setting in openDatabase as documented below) -## Browser platform usage notes - -As stated above the browser platform will be supported _(with numbered parameters working_ using [kripken / sql.js](https://github.com/kripken/sql.js) (see [litehelpers/Cordova-sqlite-storage#576](https://github.com/litehelpers/Cordova-sqlite-storage/pull/576)) in the near future. Alternative solutions for now _(with no support for numbered parameters such as `?1`, `?2`, ...)_: - -- Use [brodybits / sql-promise-helper](https://github.com/brodybits/sql-promise-helper) as described in [brodybits/sql-promise-helper#4](https://github.com/brodybits/sql-promise-helper/issues/4) -- Mocking on Ionic Native is possible as described in and - ## About this plugin version This is the common plugin version which supports the most widely used features and serves as the basis for the other versions. @@ -142,7 +135,7 @@ or using numbered parameters as documented in @@ -326,6 +323,37 @@ In addition, this guide assumes a basic knowledge of some key JavaScript concept **NOTICE:** This plugin is only supported with the Cordova CLI. This plugin is *not* supported with other Cordova/PhoneGap systems such as PhoneGap CLI, PhoneGap Build, Plugman, Intel XDK, Webstorm, etc. +## Browser platform usage notes + +As stated above the browser platform will supported with features such as numbered parameters using [kripken / sql.js](https://github.com/kripken/sql.js) (see [litehelpers/Cordova-sqlite-storage#576](https://github.com/litehelpers/Cordova-sqlite-storage/pull/576)) in the near future. Alternative solutions for now, with features such as numbered paramters (`?1`, `?2`, etc.) missing: + +1. Use [brodybits / sql-promise-helper](https://github.com/brodybits/sql-promise-helper) as described in [brodybits/sql-promise-helper#4](https://github.com/brodybits/sql-promise-helper/issues/4) +2. Mocking on Ionic Native is possible as described in and +3. Open the database as follows: + +```js +if (window.cordova.platformId === 'browser') db = window.openDatabase('MyDatabase', '1.0', 'Data', 2*1024*1024); +else db = window.sqlitePlugin.openDatabase({name: 'MyDatabase.db', location: 'default'}); +``` + +or more compactly: + +```js +db = (window.cordova.platformId === 'browser') ? + window.openDatabase('MyDatabase', '1.0', 'Data', 2*1024*1024) : + window.sqlitePlugin.openDatabase({name: 'MyDatabase.db', location: 'default'}); +``` + +(lower limit needed to avoid extra permission request popup on Safari) + +and limit database access to DRAFT standard transactions, no plugin-specific API calls: +- no `executeSql` calls outside DRAFT standard transactions +- no `sqlBatch` calls +- no `echoTest` or `selfTest` possible +- no `deleteDatabase` calls + +It would be ideal for the application code to abstract the openDatabase part away from the rest of the database access code. + ### Windows platform notes The Windows platform can present a number of challenges which increase when using this plugin. The following tips are recommended for getting started with Windows: @@ -617,7 +645,7 @@ Additional limitations are tracked in [marked Cordova-sqlite-storage doc-todo is ## Some tips and tricks -- If you run into problems and your code follows the asynchronous HTML5/[Web SQL](http://www.w3.org/TR/webdatabase/) transaction API, you can try opening a test database using `window.openDatabase` and see if you get the same problems. +- In case of issues with code that follows the asynchronous Web SQL transaction API, it is possible to test with a test database using `window.openDatabase` for comparison with (WebKit) Web SQL. - In case your database schema may change, it is recommended to keep a table with one row and one column to keep track of your own schema version number. It is possible to add it later. The recommended schema update procedure is described below. @@ -688,7 +716,6 @@ FUTURE TBD: Proper date/time handling will be further tested and documented at s ## Major TODOs - More formal documentation of API, especially for non-standard functions -- Browser platform - IndexedDBShim adapter (possibly based on IndexedDBShim) - Further cleanup of [support](#support) section - Resolve or document remaining [open Cordova-sqlite-storage bugs](https://github.com/litehelpers/Cordova-sqlite-storage/issues?q=is%3Aissue+is%3Aopen+label%3Abug-general) @@ -954,6 +981,8 @@ The following types of SQL transactions are supported by this plugin version: ### Single-statement transactions +NOTE: This call will NOT work alternative 3 for browser platform support discussed in [browser platform usage notes](#browser-platform-usage-notes). + Sample with INSERT: ```Javascript @@ -1001,6 +1030,8 @@ db.executeSql("SELECT UPPER('First') AS uppertext", [], function (resultSet) { ### SQL batch transactions +NOTE: This call will NOT work alternative 3 for browser platform support discussed in [browser platform usage notes](#browser-platform-usage-notes). + Sample: ```Javascript