diff --git a/docz/docs/02-getting-started/01-installation/03-nodejs.md b/docz/docs/02-getting-started/01-installation/03-nodejs.md index 9eb09ca..a5cf746 100644 --- a/docz/docs/02-getting-started/01-installation/03-nodejs.md +++ b/docz/docs/02-getting-started/01-installation/03-nodejs.md @@ -47,6 +47,8 @@ new versions are released! ::: +### Legacy Endpoints + :::warning Older releases are technically available on the public npm registry as `xlsx`, diff --git a/docz/docs/03-demos/02-grid/01-xs.md b/docz/docs/03-demos/02-grid/01-xs.md index 8d61779..f2198ef 100644 --- a/docz/docs/03-demos/02-grid/01-xs.md +++ b/docz/docs/03-demos/02-grid/01-xs.md @@ -14,14 +14,20 @@ With a familiar UI, `x-spreadsheet` is an excellent choice for a modern editor. [Click here for a live standalone integration demo.](pathname:///xspreadsheet/) +:::note + +This demo was last verified on 2023 September 03. + +::: + ## Live Demo -:::note +:::note pass Due to CSS conflicts between the data grid and the documentation generator, features like scrolling may not work as expected. -[The linked demo uses a simple HTML page.](pathname:///xspreadsheet/) +[The standalone demo uses a simple HTML page.](pathname:///xspreadsheet/) ::: @@ -114,5 +120,9 @@ var grid = x_spreadsheet(document.getElementById("gridctr")); #### Additional Features +:::tip pass + This demo barely scratches the surface. The underlying grid component includes many additional features that work with [SheetJS Pro](https://sheetjs.com/pro). + +::: \ No newline at end of file diff --git a/docz/docs/03-demos/02-grid/02-cdg.md b/docz/docs/03-demos/02-grid/02-cdg.md index cae6f7a..5e72635 100644 --- a/docz/docs/03-demos/02-grid/02-cdg.md +++ b/docz/docs/03-demos/02-grid/02-cdg.md @@ -8,11 +8,17 @@ pagination_next: demos/net/index -After extensive testing, `canvas-datagrid` stood out as a high-performance grid +[Canvas Datagrid](https://canvas-datagrid.js.org/) is a high-performance grid with a straightforward API. [Click here for a live standalone integration demo.](pathname:///cdg/) +:::note + +This demo was last verified on 2023 September 03. + +::: + ## Live Demo :::note @@ -133,5 +139,9 @@ XLSX.writeFile(wb, "SheetJS.xlsx"); #### Additional Features +:::tip pass + This demo barely scratches the surface. The underlying grid component includes many additional features that work with [SheetJS Pro](https://sheetjs.com/pro). + +::: \ No newline at end of file diff --git a/docz/docs/03-demos/03-net/01-network.mdx b/docz/docs/03-demos/03-net/01-network.mdx index 3c8daf0..7ece1de 100644 --- a/docz/docs/03-demos/03-net/01-network.mdx +++ b/docz/docs/03-demos/03-net/01-network.mdx @@ -773,6 +773,6 @@ Other demos show network operations in special platforms: - [React Native "Fetching Remote Data"](/docs/demos/mobile/reactnative#fetching-remote-data) - [NativeScript "Fetching Remote Files"](/docs/demos/mobile/nativescript#fetching-remote-files) -[^1]: See [`dataType` in `jQuery.ajax`](https://api.jquery.com/jQuery.ajax/#:~:text=the%20%27dataType%27%20parameter.-,dataType,-(default%3A%20Intelligent) in the official jQuery documentation. +[^1]: See [`dataType` in `jQuery.ajax`](https://api.jquery.com/jQuery.ajax/) in the official jQuery documentation. [^2]: See [the official `jquery.binarytransport.js` repo](https://github.com/henrya/js-jquery/tree/master/BinaryTransport) for more details. [^3]: See ["Fluent interface"](https://en.wikipedia.org/wiki/Fluent_interface) on Wikipedia. \ No newline at end of file diff --git a/docz/docs/03-demos/05-mobile/01-reactnative.md b/docz/docs/03-demos/05-mobile/01-reactnative.md index 40cf09b..1ce14d6 100644 --- a/docz/docs/03-demos/05-mobile/01-reactnative.md +++ b/docz/docs/03-demos/05-mobile/01-reactnative.md @@ -215,11 +215,11 @@ const wb = XLSX.read(ab); :::note -This demo was tested on an Intel Mac on 2023 August 20 with RN `0.72.4`. +The Android demo was last tested on 2023 September 03 with RN `0.72.4`. The +simulator used Android 13 ("Tiramisu") API 33 on a Pixel 3. -The iOS simulator runs iOS 16.2 on an iPhone SE (3rd generation). - -The Android simulator runs Android 12.0 (S) API 31 on a Pixel 3. +The iOS demo was last tested on 2023 September 03 with RN `0.72.4`. The +simulator used iOS 16.4 on an iPhone SE (3rd generation). ::: diff --git a/docz/docs/03-demos/05-mobile/03-quasar.md b/docz/docs/03-demos/05-mobile/03-quasar.md index 63dea30..c9d22c6 100644 --- a/docz/docs/03-demos/05-mobile/03-quasar.md +++ b/docz/docs/03-demos/05-mobile/03-quasar.md @@ -178,7 +178,7 @@ cordova plugin add cordova-plugin-wkwebview-engine cordova plugin add cordova-plugin-file ``` -:::note +:::note pass If there is an error `Could not load API for iOS project`, it needs to be reset: diff --git a/docz/docs/03-demos/05-mobile/04-ionic.md b/docz/docs/03-demos/05-mobile/04-ionic.md index dda3eea..8369cbb 100644 --- a/docz/docs/03-demos/05-mobile/04-ionic.md +++ b/docz/docs/03-demos/05-mobile/04-ionic.md @@ -57,7 +57,7 @@ npx @capacitor/cli telemetry ## Integration Details -:::caution +:::caution pass The latest version of Ionic uses CapacitorJS. These notes are for Cordova apps. The [CapacitorJS demo](/docs/demos/mobile/capacitor) covers CapacitorJS apps. diff --git a/docz/docs/03-demos/05-mobile/05-capacitor.md b/docz/docs/03-demos/05-mobile/05-capacitor.md index cc8cc3c..d7252b3 100644 --- a/docz/docs/03-demos/05-mobile/05-capacitor.md +++ b/docz/docs/03-demos/05-mobile/05-capacitor.md @@ -115,17 +115,31 @@ async function exportFile() { :::note -This demo was tested on an Intel Mac on 2023 April 01 with Capacitor 4.7.3 and -`@capacitor/filesystem` 4.1.4 +The Android demo was last tested on 2023 September 03 with CapacitorJS `5.3.0` +and filesystem `5.1.3` on an emulated Pixel 3 + Android 13 ("Tiramisu") API 33. -The iOS simulator runs iOS 16.2 on an iPhone 14 Pro Max. - -The Android simulator runs Android 12.0 (S) API 31 on a Pixel 3. +The iOS demo was last tested on 2023 September 03 with CapacitorJS `5.3.0` +and filesystem `5.1.3` on an emulated iPhone SE (3rd generation) + iOS 16.4. ::: ### Base Project +0) Follow the official "Environment Setup"[^1] instructions to set up Android +and iOS targets + +:::caution pass + +iOS development is only supported on macOS. + +::: + +
Installation Notes (click to show) + +CapacitorJS requires Java 17. + +
+ 1) Disable telemetry. ```bash @@ -167,22 +181,63 @@ npm run build curl -o src/App.svelte -L https://docs.sheetjs.com/cap/App.svelte ``` +### Android + +6) Create Android app + +```bash +npm i --save @capacitor/android +npx cap add android +``` + +7) Enable file reading and writing in the Android app. + +The following lines must be added to `android/app/src/main/AndroidManifest.xml` +after the `Permissions` comment: + +```xml title="android/app/src/main/AndroidManifest.xml (add to file)" + + + + + + + + +``` + +8) Run the app in the simulator + +```bash +npm run build +npx cap sync +npx cap run android +``` + +9) Test the app + +Open the app and observe that presidents are listed in the table. + +Touch "Export XLSX" and the emulator will ask for permission: + +Tap "Allow" and a popup will be displayed with a path. + +To see the generated file, switch to the "Files" app in the simulator, tap the +`≡` icon and tap "Documents". Tap "Documents" folder to find `SheetJSCap.xlsx`. + ### iOS -6) Follow the [React Native demo](/docs/demos/mobile/reactnative#demo) to -ensure the iOS simulator is ready. - -7) Create iOS app +10) Create iOS app ```bash npm i --save @capacitor/ios npx cap add ios ``` -8) Enable file sharing and make the documents folder visible in the iOS app. +11) Enable file sharing and make the documents folder visible in the iOS app. The following lines must be added to `ios/App/App/Info.plist`: -```xml title="ios/App/App/Info.plist" +```xml title="ios/App/App/Info.plist (add to file)" @@ -196,7 +251,7 @@ The following lines must be added to `ios/App/App/Info.plist`: (The root element of the document is `plist` and it contains one `dict` child) -9) Run the app in the simulator +12) Run the app in the simulator ```bash npm run build @@ -204,7 +259,7 @@ npx cap sync npx cap run ios ``` -10) Test the app +13) Test the app Open the app and observe that presidents are listed in the table. @@ -213,48 +268,4 @@ Touch "Export XLSX" and a popup will be displayed. To see the generated file, switch to the "Files" app in the simulator and look for `SheetJSCap.xlsx` in "On My iPhone" > "`sheetjs-cap`" -### Android - -11) Follow the [React Native demo](/docs/demos/mobile/reactnative#demo) to -ensure the Android simulator is ready. - -12) Create Android app - -```bash -npm i --save @capacitor/android -npx cap add android -``` - -13) Enable file reading and writing in the Android app. -The following lines must be added to `android/app/src/main/AndroidManifest.xml` -after the `Permissions` comment: - -```xml title="android/app/src/main/AndroidManifest.xml" - - - - - - - - -``` - -14) Run the app in the simulator - -```bash -npm run build -npx cap sync -npx cap run android -``` - -15) Test the app - -Open the app and observe that presidents are listed in the table. - -Touch "Export XLSX" and the emulator will ask for permission: - -Tap "Allow" and a popup will be displayed with a path. - -To see the generated file, switch to the "Files" app in the simulator, tap the -`≡` icon and tap "Documents". Tap "Documents" folder to find `SheetJSCap.xlsx`. +[^1]: See ["Environment Setup"](https://capacitorjs.com/docs/getting-started/environment-setup) in the CapacitorJS documentation. \ No newline at end of file diff --git a/docz/docs/03-demos/05-mobile/06-flutter.md b/docz/docs/03-demos/05-mobile/06-flutter.md index 13c8e7c..da0f8d8 100644 --- a/docz/docs/03-demos/05-mobile/06-flutter.md +++ b/docz/docs/03-demos/05-mobile/06-flutter.md @@ -197,12 +197,13 @@ class SheetJSFlutterState extends State { :::note -This demo was tested on an Intel Mac on 2023-08-18 with Flutter 3.13.0, Dart -3.1.0, and `flutter_js` 0.8.0. +The Android demo was last tested on 2023 September 03 with Flutter `3.13.2`. The +simulator used Android 13 ("Tiramisu") API 33 on a Pixel 3. -The iOS simulator runs iOS 16.2 on an iPhone 14 Pro Max. +The iOS demo was last tested on 2023 September 03 with Flutter `3.13.2`. The +simulator used iOS 16.4 on an iPhone SE (3rd generation). -The Android simulator runs Android 12.0 (S) API 31 on a Pixel 3. +Both tests used Dart 3.1.0 and Flutter JS plugin version `0.8.0`. ::: @@ -257,7 +258,7 @@ Run `flutter emulators` and check for both `ios` and `android` emulators: ``` apple_ios_simulator • iOS Simulator • Apple • ios -Pixel_3_API_31 • Pixel 3 API 31 • Google • android +Pixel_3_API_33 • Pixel 3 API 33 • Google • android ``` 1) Disable telemetry. @@ -278,14 +279,76 @@ flutter create sheetjs_flutter cd sheetjs_flutter ``` -3) Open the iOS simulator. +3) Start the Android emulator. -4) While the iOS simulator is open, start the application: +
Details (click to hide) + +**Android Studio** + +In Android Studio, click "More actions" > "Virtual Device Manager". Look for the +emulated device in the list and click the ▶ button to play. + +**Command Line** + +List the available emulators with `flutter emulators`: + +``` +% flutter emulators +2 available emulators: + +apple_ios_simulator • iOS Simulator • Apple • ios +Pixel_3_API_33 • Pixel 3 API 33 • Google • android +^^^^^^^^^^^^^^--- the first column is the name +``` + +The first column shows the name that should be passed to `emulator -avd`. In a +previous test, the name was `Pixel_3_API_33` and the launch command was: + +``` +% emulator -avd Pixel_3_API_33 +``` + +
+ +4) While the Android emulator is open, start the application: ```bash flutter run ``` +
If emulator is not detected (click to show) + +In some test runs, `flutter run` did not automatically detect the emulator. + +Run `flutter -v -d sheetjs run` and the command will fail. Inspect the output: + +```text title="Command output" +// highlight-next-line +[ +6 ms] No supported devices found with name or id matching 'sheetjs'. +[ ] The following devices were found: +... +// highlight-next-line +[ +26 ms] sdk gphone64 arm64 (mobile) • emulator-5554 • android-arm64 • Android 13 (API 33) (emulator) +[ ] macOS (desktop) • macos • darwin-arm64 • macOS 13.5.1 22G90 darwin-arm64 +... +``` + +Search the output for `sheetjs`. After that line, search for the emulator list. +One of the lines will correspond to the running emulator: + +``` +[ +26 ms] sdk gphone64 arm64 (mobile) • emulator-5554 • android-arm64 • Android 13 (API 33) (emulator) + ^^^^^^^^^^^^^--- the second column is the name +``` + +The second column is the device name. Assuming the name is `emulator-5554`, run: + +```bash +flutter -v -d emulator-5554 run +``` + +
+ Once the app loads, stop the terminal process and close the simulator. 5) Install Flutter / Dart dependencies: @@ -323,38 +386,11 @@ cd ..`} curl -L -o lib/main.dart https://docs.sheetjs.com/flutter/main.dart ``` -### iOS - -9) Start the iOS simulator again. - -10) Launch the app: - -```bash -flutter run -``` - -The app fetches , parses, converts data to an -array of arrays, and presents the data in a Flutter `Table` widget. - -11) Close the iOS simulator. - ### Android -12) Start the Android emulator with `emulator -avd name_of_device`. The actual -emulator name can be found with `flutter emulators`: +9) Start the Android emulator using the same instructions as Step 3. -``` -% flutter emulators -2 available emulators: - -apple_ios_simulator • iOS Simulator • Apple • ios -Pixel_3_API_31 • Pixel 3 API 31 • Google • android -^^^^^^^^^^^^^^--- the first column is the name - -% emulator -avd Pixel_3_API_31 -``` - -13) Launch the app: +10) Launch the app: ```bash flutter run @@ -387,13 +423,27 @@ Searching for `minSdkVersion` should reveal the following line: `flutter.minSdkVersion` should be replaced with `21`: -```diff title="android\app\build.gradle (diff)" -- minSdkVersion flutter.minSdkVersion -+ minSdkVersion 21 +```text title="android\app\build.gradle" + minSdkVersion 21 ``` ::: +11) Close the Android emulator. + +### iOS + +12) Start the iOS simulator. + +13) Launch the app: + +```bash +flutter run +``` + +The app fetches , parses, converts data to an +array of arrays, and presents the data in a Flutter `Table` widget. + [^1]: is the official site for the Dart Programming Language. [^2]: is the official site for the Flutter Framework. [^3]: [The `flutter_js` package](https://pub.dev/packages/flutter_js) is hosted on the Dart package repository. diff --git a/docz/docs/03-demos/06-desktop/01-electron.md b/docz/docs/03-demos/06-desktop/01-electron.md index ff2a19b..709c0df 100644 --- a/docz/docs/03-demos/06-desktop/01-electron.md +++ b/docz/docs/03-demos/06-desktop/01-electron.md @@ -180,7 +180,15 @@ function exportFile(workbook) { :::note -This demo was tested on 2023 February 20 with Electron 23.0.0. +This demo was tested in the following environments: + +| OS and Version | Arch | Electron | Date | +|:---------------|:-----|:---------|:-----------| +| macOS 13.5.1 | ARM | `26.1.0` | 2023-09-03 | +| macOS 13.5.1 | x64 | `26.1.0` | 2023-09-03 | +| Windows 10 | x64 | `26.1.0` | 2023-09-03 | +| Linux (HoloOS) | x64 | `26.1.0` | 2023-09-03 | +| Linux (Debian) | ARM | `26.1.0` | 2023-09-03 | ::: @@ -218,7 +226,11 @@ curl -LO https://docs.sheetjs.com/electron/index.html curl -LO https://docs.sheetjs.com/electron/index.js ``` -2) Run `npm i` to install dependencies. +2) Install dependencies: + +```bash +npm install +``` 3) To verify the app works, run in the test environment: @@ -226,8 +238,7 @@ curl -LO https://docs.sheetjs.com/electron/index.js npx -y electron . ``` -The app will show and you should be able to verify reading and writing by using -the relevant buttons to open files and clicking the export button. +The app will show. 4) To build a standalone app, run the builder: @@ -235,8 +246,52 @@ the relevant buttons to open files and clicking the export button. npm run make ``` -This will generate the standalone app in the `out\sheetjs-electron-...` folder. -For a recent Intel Mac, the path will be `out/sheetjs-electron-darwin-x64/` +This will create a package in the `out\make` folder. + +:::caution pass + +On Linux, the packaging step may require additional dependencies[^1] + +::: + +**Testing** + +5) Download [the test file `pres.numbers`](https://sheetjs.com/pres.numbers) + +6) Re-launch the application in the test environment: + +```bash +npx -y electron . +``` + +_Electron API_ + +7) Click "Click here to select a file from your computer". With the file picker, +navigate to the Downloads folder and select `pres.numbers`. + +The application should show data in a table. + +8) Click "Export Data!" and click "Save" in the popup. By default, it will try +to write to `Untitled.xls` in the Downloads folder. + +The app will show a popup once the data is exported. Open the file in a +spreadsheet editor and compare the data to the table shown in the application. + +_Drag and Drop_ + +9) Close the application, end the terminal process and re-launch (see step 6) + +10) Open the Downloads folder in a file explorer or finder window. + +11) Click and drag the `pres.numbers` file from the Downloads folder to the +bordered "Drop a spreadsheet file" box. The file data should be displayed. + +_File Input Element_ + +12) Close the application, end the terminal process and re-launch (see step 6) + +13) Click "Choose File". With the file picker, navigate to the Downloads folder +and select `pres.numbers`. ## Electron Breaking Changes @@ -263,3 +318,5 @@ Electron 14+ must use `@electron/remote` instead of `remote`. An `initialize` call is required to enable Developer Tools in the window. ::: + +[^1]: See ["Makers"](https://www.electronforge.io/config/makers) in the Electron Forge documentation. \ No newline at end of file diff --git a/docz/docs/03-demos/07-data/29-pouchdb.md b/docz/docs/03-demos/07-data/29-pouchdb.md index 23a6a00..b943b3c 100644 --- a/docz/docs/03-demos/07-data/29-pouchdb.md +++ b/docz/docs/03-demos/07-data/29-pouchdb.md @@ -1,5 +1,6 @@ --- -title: PouchDB +title: Sheets in PouchDB +sidebar_label: PouchDB pagination_prev: demos/desktop/index pagination_next: demos/local/index sidebar_custom_props: @@ -9,15 +10,79 @@ sidebar_custom_props: import current from '/version.js'; import CodeBlock from '@theme/CodeBlock'; -PouchDB is a pure JS database with built-in synchronization features. +[PouchDB](https://pouchdb.com/) is a pure JavaScript database with built-in +synchronization features and offline support. + +[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing +data from spreadsheets. + +This demo uses PouchDB and SheetJS to export database snapshots to spreadsheets +and import bulk data from workbooks. We'll explore the subtleties of processing +arrays of objects to mesh with both libraries. + +The ["Complete Example"](#complete-example) section imbues the official "Todos" +demo with the ability to export the list to XLSX workbooks. + +:::note + +This demo was last tested on 2023 September 04 against PouchDB 8.0.1 standalone +browser script in Chrome 116. + +::: ## Integration Details -`Database#allDocs` is the standard approach for bulk data export. The generated +SheetJS CE offers standalone scripts, NodeJS modules, ESM modules, and other +scripts. The ["Installation"](/docs/getting-started/installation) section covers +a number of common deployment scenarios. + +PouchDB ships with standalone scripts for browser use and NodeJS modules for use +in server-side scripts[^1]. + +The `PouchDB` constructor returns a `Database` object. + +#### Importing Data + +`Database#bulkDocs`[^2] is the standard approach for bulk data import. The method +accepts "arrays of objects" that can be generated through the SheetJS +`sheet_to_json`[^3] method. + +If rows do not include the `_id` parameter, the database will automatically +assign an ID per row. It is strongly recommended to generate the `_id` directly. + +This method starts from a SheetJS workbook object[^4] and uses data from the +first sheet. `read` and `readFile`[^5] can generate workbook objects from files. + +```js +async function push_first_sheet_to_pouchdb(db, wb, _id_) { + /* get first worksheet */ + const ws = wb.Sheets[wb.SheetNames[0]]; + + /* generate array of arrays */ + const aoo = XLSX.utils.sheet_to_json(ws); + + /* if a prefix is specified, add a unique _id to each row based on index */ + if(typeof _id_ == "string") aoo.forEach((row, idx) => row._id = _id_ + idx); + + /* perform query */ + return await db.bulkDocs(aoo); +} +``` + +:::note pass + +Existing data can be erased with `Database#destroy`. + +::: + +#### Exporting Data + +`Database#allDocs`[^6] is the standard approach for bulk data export. Generated row objects have additional `_id` and `_rev` keys that should be removed. -Nested objects must be flattened. The ["Export Tutorial"](/docs/getting-started/examples/export) -includes an example of constructing a simple array. +After removing the PouchDB internal fields, the SheetJS `json_to_sheet`[^7] +method can generate a worksheet. Other utility functions[^8] can construct a +workbook. The workbook can be exported with the SheetJS `writeFile`[^9] method: ```js function export_pouchdb_to_xlsx(db) { @@ -42,6 +107,17 @@ function export_pouchdb_to_xlsx(db) { } ``` +:::caution pass + +`json_to_sheet` expects an array of "flattened" objects where each value is a +simple data type that can be stored in a spreadsheet cell. If document objects +have a nested structure, integration code should post-process the data. + +["Export Tutorial"](/docs/getting-started/examples/export#reshaping-the-array) +processes data from an API and computes a few text values from the nested data. + +::: + ## Complete Example 0) Download the "Working Version" from the Getting Started guide. @@ -75,16 +151,28 @@ cd getting-started-todo-master
`} -3) Just before the end of `app.js`, add a `click` event listener: +3) Near the end of `index.html`, look for a script tag referencing a CDN: -```js title="app.js" +```html title="index.html" + +``` + +Upgrade PouchDB by changing the `src` attribute to the production build[^10]: + +```html + +``` + +4) Just before the end of `js/app.js`, add a `click` event listener: + +```js title="js/app.js" if (remoteCouch) { sync(); } // highlight-start document.getElementById("xport").addEventListener("click", function() { - db.allDocs({include_docs: true}, function(err, doc) { + db.allDocs({include_docs: true, descending: true}, function(err, doc) { const aoo = doc.rows.map(r => { const { _id, _rev, ... rest } = r.doc; return rest; @@ -98,11 +186,57 @@ cd getting-started-todo-master })(); ``` -4) Start a local web server: +:::info pass + +The demo UI reads the todo items in descending order: + +```js title="js/app.js" + //------------------------------VVVVVVVVVVVVVVVV (descending order) + db.allDocs({include_docs: true, descending: true}, function(err, doc) { + redrawTodosUI(doc.rows); + }); +``` + +The new callback function also specifies `descending: true` to ensure that the +order of todo items in the export matches the list displayed in the webpage. + +::: + +5) Start a local web server: ```bash npx http-server . ``` -Access `http://localhost:8080` from your browser. Add a few items and click -the "Export!" button to generate a new file. +The command will display a URL (typically `http://localhost:8080`) which can be +opened in a web browser. + +**Testing** + +6) Access the URL from step 5 with a web browser. + +7) Add two items "Sheet" and "js". Mark "Sheet" as completed. The page should +look like the following screenshot: + +![todos screenshot](pathname:///pouchdb/todos.png) + +8) Click the "Export!" text at the top of the page. The site should create an +export named "SheetJSPouch.xlsx" + +9) Open the file in a spreadsheet editor. It should match the following table: + +| title | completed | +|:------|:----------| +| Sheet | TRUE | +| js | FALSE | + +[^1]: See ["Setting up PouchDB"](https://pouchdb.com/guides/setup-pouchdb.html) in the PouchDB documentation. +[^2]: See ["Create/update a batch of documents"](https://pouchdb.com/api.html#batch_create) in the PouchDB API documentation +[^3]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output) +[^4]: See ["SheetJS Data Model"](/docs/csf) +[^5]: See [`read` in "Reading Files"](/docs/api/parse-options) +[^6]: See ["Fetch a batch of documents"](https://pouchdb.com/api.html#batch_fetch) in the PouchDB API documentation +[^7]: See [`json_to_sheet` in "Utilities"](/docs/api/utilities/array#array-of-objects-input) +[^8]: See ["Workbook Helpers" in "Utilities"](/docs/api/utilities/wb) for details on `book_new` and `book_append_sheet`. +[^9]: See [`writeFile` in "Writing Files"](/docs/api/write-options) +[^10]: The ["Quick Start" section of "Download"](https://pouchdb.com/download.html#file) in the PouchDB website describes the recommended CDN for PouchDB scripts. \ No newline at end of file diff --git a/docz/docs/03-demos/09-cloud/22-airtable.md b/docz/docs/03-demos/09-cloud/22-airtable.md index 0f4f11e..0e0f576 100644 --- a/docz/docs/03-demos/09-cloud/22-airtable.md +++ b/docz/docs/03-demos/09-cloud/22-airtable.md @@ -7,13 +7,28 @@ pagination_next: demos/extensions/index import current from '/version.js'; import CodeBlock from '@theme/CodeBlock'; +[Airtable](https://airtable.com/) is a collaborative dataset hosting service. + +[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing +data from spreadsheets. + +This demo uses SheetJS to properly exchange data with spreadsheet files. We'll +explore how to use the `airtable` NodeJS library and SheetJS in two data flows: + +- "Exporting data": Data in Airtable will be pulled into an array of objects and +exported to XLSB spreadsheets using SheetJS libraries. + +- "Importing data": Data in an XLSX spreadsheet will be parsed using SheetJS +libraries and appended to a dataset in Airtable + + +## NodeJS Integration + Airtable recommends Personal Access Tokens for interacting with their API. When fetching data from the API, the result will include an array of row objects that can be converted to a worksheet with `XLSX.utils.json_to_sheet`. The API methods to write data will accept row objects generated by `XLSX.utils.sheet_to_json`. -## NodeJS Integration - The main module is `airtable` and can be installed with `npm`: {`\ @@ -52,7 +67,7 @@ async function airtable_to_worksheet(table) { } ``` -:::caution +:::caution pass The results are not guaranteed to be sorted. The official API includes options for sorting by fields. @@ -83,16 +98,16 @@ async function airtable_load_worksheet(table, worksheet) { :::note -This demo was last tested on 2023 February 15. At the time, it was possible to -create a free account with API access. +This demo was last tested on 2023 September 03. At the time, free accounts +included limited API access. ::: -0) Create a free Airtable account. +0) Create a free Airtable account and verify the email address. ### Personal Access Token -:::note +:::note pass In the past, Airtable offered API keys. They are slated to deprecate API keys in January 2024. They recommend "Personal Access Tokens" for operations. @@ -137,9 +152,9 @@ the first part after the `.com` will be the workspace name. ### Exporting Data -8) Save the following to `read.js`: +8) Save the following to `SheetJSAirtableRead.js`: -```js title="read.js" +```js title="SheetJSAirtableRead.js" const Airtable = require("airtable"), XLSX = require("xlsx"); // highlight-start /* replace the value with the personal access token */ @@ -161,12 +176,23 @@ const base = "app..."; 9) Replace the values in the highlighted lines with the PAT and workspace name. -10) Run `node read.js`. The script should write `SheetJSAirtable.xlsb`. The file -can be opened in Excel. +10) Install dependencies: + +{`\ +npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz airtable`} + + +11) Run the script: + +```bash +node SheetJSAirtableRead.js +``` + +The script should write `SheetJSAirtable.xlsb`. The file can be opened in Excel. ### Importing Data -11) Create a file `SheetJSAirpend.xlsx` with some new records in sheet `Sheet1`: +12) Create a file `SheetJSAirpend.xlsx` with some new records in sheet `Sheet1`: ![Records to append](pathname:///airtable/airpend.png) @@ -178,9 +204,9 @@ Name,Index Someone Else,47 ``` -12) Save the following to `write.js`: +13) Save the following to `SheetJSAirtableWrite.js`: -```js title="write.js" +```js title="SheetJSAirtableWrite.js" const Airtable = require("airtable"), XLSX = require("xlsx"); // highlight-start /* replace the value with the personal access token */ @@ -198,8 +224,20 @@ const base = "app..."; })(); ``` -13) Replace the values in the highlighted lines with the PAT and workspace name. +14) Replace the values in the highlighted lines with the PAT and workspace name. -14) Run `node write.js`. Open Airtable and verify the new row: +15) Install dependencies: + +{`\ +npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz airtable`} + + +16) Run the script: + +```bash +node SheetJSAirtableWrite.js +``` + +Open Airtable and verify the new row was added: ![Final Result in Airtable](pathname:///airtable/post.png) \ No newline at end of file diff --git a/docz/docs/03-demos/10-extensions/01-extendscript.md b/docz/docs/03-demos/32-extensions/01-extendscript.md similarity index 100% rename from docz/docs/03-demos/10-extensions/01-extendscript.md rename to docz/docs/03-demos/32-extensions/01-extendscript.md diff --git a/docz/docs/03-demos/10-extensions/02-chromium.md b/docz/docs/03-demos/32-extensions/02-chromium.md similarity index 100% rename from docz/docs/03-demos/10-extensions/02-chromium.md rename to docz/docs/03-demos/32-extensions/02-chromium.md diff --git a/docz/docs/03-demos/10-extensions/03-excelapi.md b/docz/docs/03-demos/32-extensions/03-excelapi.md similarity index 87% rename from docz/docs/03-demos/10-extensions/03-excelapi.md rename to docz/docs/03-demos/32-extensions/03-excelapi.md index 2c22348..6ca68a9 100644 --- a/docz/docs/03-demos/10-extensions/03-excelapi.md +++ b/docz/docs/03-demos/32-extensions/03-excelapi.md @@ -7,7 +7,7 @@ pagination_next: demos/bigdata/index import current from '/version.js'; import CodeBlock from '@theme/CodeBlock'; -:::info +:::info pass This demo focuses on the JavaScript API included with Excel. For reading and writing Excel files, [other demos](/docs/demos/) cover a wide variety of use cases @@ -30,7 +30,7 @@ Function parameters are covered in the official Office JavaScript API docs. :::note -This demo was last tested on 2023 April 20 against Excel 365 (version 2303) +This demo was last tested on 2023 September 03 against Excel 365 (version 2308) ::: @@ -87,7 +87,17 @@ async function extern(url) { - Open File Explorer - Select the address bar and enter `%LOCALAPPDATA%\Microsoft\Office\16.0\Wef` -- Delete `CustomFunctions` and empty Recycle Bin. +- Delete the `CustomFunctions` folder (if it exists) and empty Recycle Bin. + +:::caution pass + +**This will delete all custom functions associated with the user account!** + +To preserve the custom functions on the user account, rename the existing folder +to `CustomFunctionsBackup` before testing and rename back to `CustomFunctions` +after testing is finished. + +::: 1) Install [NodeJS LTS](https://nodejs.org/en/download/). @@ -158,7 +168,7 @@ function version() { Excel window (do not save the Excel file). Re-run `npm start`. 10) In the new Excel window, enter the formula `=SHEETJS.VERSION()` in cell -`E1`. You should see something similar to the following screenshot: +`D1`. You should see something similar to the following screenshot: ![`SHEETJS.VERSION` output](pathname:///xlapi/xlvers.png) @@ -168,7 +178,7 @@ This indicates that the SheetJS library has been loaded. 11) Add the following code snippet to `src\functions\functions.js`: -```js src\functions\functions.js +```js title="src\functions\functions.js (add to end)" /** * Download file and write data * @customfunction @@ -201,7 +211,7 @@ Excel window (do not save the Excel file). Re-run `npm start`. formula `=SHEETJS.EXTERN(D1)` in cell `D2` and press Enter. Excel should pull in the data and generate a dynamic array. -:::note +:::tip pass [SheetJS Pro](https://sheetjs.com/pro) offers additional features that can be used in Excel Custom Functions and Add-ins diff --git a/docz/docs/03-demos/10-extensions/04-gsheet.md b/docz/docs/03-demos/32-extensions/04-gsheet.md similarity index 100% rename from docz/docs/03-demos/10-extensions/04-gsheet.md rename to docz/docs/03-demos/32-extensions/04-gsheet.md diff --git a/docz/docs/03-demos/10-extensions/06-osa.md b/docz/docs/03-demos/32-extensions/06-osa.md similarity index 99% rename from docz/docs/03-demos/10-extensions/06-osa.md rename to docz/docs/03-demos/32-extensions/06-osa.md index 2f792ad..541b93b 100644 --- a/docz/docs/03-demos/10-extensions/06-osa.md +++ b/docz/docs/03-demos/32-extensions/06-osa.md @@ -20,7 +20,7 @@ available as a global. A JS stub can expose methods from AppleScript scripts. :::note -This demo was last tested on 2023 April 18 in macOS Monterey. +This demo was last tested on 2023-09-03 in macOS Ventura. ::: diff --git a/docz/docs/03-demos/10-extensions/09-mathematica.md b/docz/docs/03-demos/32-extensions/09-mathematica.md similarity index 100% rename from docz/docs/03-demos/10-extensions/09-mathematica.md rename to docz/docs/03-demos/32-extensions/09-mathematica.md diff --git a/docz/docs/03-demos/10-extensions/_category_.json b/docz/docs/03-demos/32-extensions/_category_.json similarity index 63% rename from docz/docs/03-demos/10-extensions/_category_.json rename to docz/docs/03-demos/32-extensions/_category_.json index be66d80..cd43a7b 100644 --- a/docz/docs/03-demos/10-extensions/_category_.json +++ b/docz/docs/03-demos/32-extensions/_category_.json @@ -1,4 +1,4 @@ { "label": "App Extensions", - "position": 10 + "position": 32 } \ No newline at end of file diff --git a/docz/docs/03-demos/10-extensions/index.md b/docz/docs/03-demos/32-extensions/index.md similarity index 100% rename from docz/docs/03-demos/10-extensions/index.md rename to docz/docs/03-demos/32-extensions/index.md diff --git a/docz/docs/03-demos/42-engines/02_v8.md b/docz/docs/03-demos/42-engines/02_v8.md index c135caa..f484069 100644 --- a/docz/docs/03-demos/42-engines/02_v8.md +++ b/docz/docs/03-demos/42-engines/02_v8.md @@ -679,7 +679,7 @@ cl /MT /I..\v8\v8\ /I..\v8\v8\include sheetjs.v8.cc /GR- v8_monolith.lib Advapi3 ```bash -cl /MT /I..\v8\v8\ /I..\v8\v8\include sheetjs.v8.cc /GR- v8_monolith.lib Advapi32.lib Winmm.lib Dbghelp.lib /std:c++17 /DV8_COMPRESS_POINTERS=1 /DV8_ENABLE_SANDBOX /link /out:sheetjs.v8.exe /LIBPATH:..\v8\v8\out.gn\x64.release.sample\obj\ +.\sheetjs.v8.exe pres.numbers ``` diff --git a/docz/static/electron/package.json b/docz/static/electron/package.json index 66f0235..323e2c0 100644 --- a/docz/static/electron/package.json +++ b/docz/static/electron/package.json @@ -1,10 +1,12 @@ { "name": "sheetjs-electron", "author": "sheetjs", + "description": "Spreadsheet Data Import and Export with SheetJS + Electron", + "license": "Apache-2.0", "version": "0.0.0", "main": "main.js", "dependencies": { - "@electron/remote": "2.0.9", + "@electron/remote": "2.0.11", "xlsx": "https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz" }, "scripts": { @@ -13,12 +15,12 @@ "make": "electron-forge make" }, "devDependencies": { - "@electron-forge/cli": "6.0.5", - "@electron-forge/maker-deb": "6.0.5", - "@electron-forge/maker-rpm": "6.0.5", - "@electron-forge/maker-squirrel": "6.0.5", - "@electron-forge/maker-zip": "6.0.5", - "electron": "23.0.0" + "@electron-forge/cli": "6.4.1", + "@electron-forge/maker-deb": "6.4.1", + "@electron-forge/maker-rpm": "6.4.1", + "@electron-forge/maker-squirrel": "6.4.1", + "@electron-forge/maker-zip": "6.4.1", + "electron": "26.1.0" }, "config": { "forge": { diff --git a/docz/static/pouchdb/todos.png b/docz/static/pouchdb/todos.png new file mode 100644 index 0000000..3c6d4ea Binary files /dev/null and b/docz/static/pouchdb/todos.png differ diff --git a/docz/static/xlapi/xlvers.png b/docz/static/xlapi/xlvers.png index 4bb185e..7eddbc5 100644 Binary files a/docz/static/xlapi/xlvers.png and b/docz/static/xlapi/xlvers.png differ