diff --git a/docz/docs/02-installation/06-amd.md b/docz/docs/02-installation/06-amd.md new file mode 100644 index 0000000..39d27a4 --- /dev/null +++ b/docz/docs/02-installation/06-amd.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 6 +sidebar_custom_props: + summary: NetSuite, RequireJS and other module systems +--- + +import current from '/version.js'; + +# AMD + +Each standalone release script is available at . + +`xlsx.full.min.js` supports AMD with name `xlsx` out of the box. + +
https://cdn.sheetjs.com/xlsx-{current}/package/dist/xlsx.full.min.js is the URL for {current}

+ +## NetSuite + +After downloading the script, it can be referenced directly in `define` calls +in SuiteScripts: + +```js +define(['N/file', './xlsx.full.min'], function(file, XLSX) { + // ... use XLSX here +}) +``` + +As explained in the [NetSuite demo](../getting-started/demos/netsuite), module +aliases are created in config files referenced via `@NAmdConfig` comments. + +## RequireJS + +After downloading the script, it can be referenced directly in `require` calls: + +```js +require(['./xlsx.full.min'], function(XLSX) { + // ... use XLSX here +}); +``` + +The `requirejs.config` function can define aliases through the `paths` key: + +```js +requirejs.config({ + paths: { + xlsx: [ './xlsx.full.min' ] + } +}); +``` diff --git a/docz/docs/04-getting-started/03-demos/04-netsuite.md b/docz/docs/04-getting-started/03-demos/04-netsuite.md new file mode 100644 index 0000000..a4b31e3 --- /dev/null +++ b/docz/docs/04-getting-started/03-demos/04-netsuite.md @@ -0,0 +1,88 @@ +--- +sidebar_position: 5 +--- + +# NetSuite + +This demo discusses the key SheetJS operations. Familiarity with SuiteScript 2 +is assumed. The following sections of the SuiteScript documentation should be +perused before reading this demo: + +- [SuiteScript 2.x API Introduction](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_4387172221.html) + is an introduction that includes a simple example with deployment details, +- [SuiteScript 2.x Custom Modules](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/chapter_4704097697.html) + covers custom modules and adding third party scripts to modules. +- [`N/file` Module](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4205693274.html) + covers the `N/file` module. It is the main API for interacting with files. + +The library plays nice with each script type, including RESTlets and Suitelets. + +## Loading the SheetJS Standalone Script + +[This script](https://cdn.sheetjs.com/xlsx-latest/package/dist/xlsx.full.min.js) +plays nice with SuiteScript `define`. It should be downloaded and uploaded to +the File Cabinet. + +After uploading, create a JSON configuration file (or add the alias to an +existing config file). The reference points to the file and omits the `.js`. + +```json +{ + "paths": { + // highlight-next-line + "xlsx": "/SuiteScripts/xlsx.full.min" + } +} +``` + +This config file should be referenced in SuiteScripts using `@NAmdConfig`. This +part is documented in ["Import a third-party JavaScript Library"](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4704111062.html#bridgehead_4738199877): + +```js +/** +* @NApiVersion 2.x +// highlight-next-line +* @NAmdConfig ./JsLibraryConfig.json +* ... more options ... +*/ +// highlight-next-line +define(['N/file', 'xlsx'], function(file, XLSX) { + ... +}); +``` + +## Reading Files + +`N/file` provides [`file.load`](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4226574300.html) +for pulling files: + +[`File#getContents`](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4229269811.html) +returns the data as a Base64-encoded string which can be read with `XLSX.read`: + +```js +/* load file */ +var f = file.load({ id: id_of_file }); +/* parse */ +var workbook = XLSX.read(f.getContents(), {type: "base64"}); +``` + +## Writing Files + +`N/file` provides [`file.create`](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_4223861820.html) +and `file.load` for creating and loading files respectively. + +Binary content must be base64-encoded. Fortunately, `XLSX.write` with `base64` +type will generate compatible Base64 strings: + +```js +/* write XLSX workbook as base64 string */ +var out = XLSX.write(workbook, { bookType: "xlsx", type: "base64" }); +/* create file */ +var newfile = file.create({ + name: 'test.xlsx', // replace with desired name + fileType: file.Type.EXCEL, + contents: out +}); +/* save */ +newfile.save(); +``` diff --git a/docz/docs/04-getting-started/03-demos/index.md b/docz/docs/04-getting-started/03-demos/index.md index 40ac92f..ca56304 100644 --- a/docz/docs/04-getting-started/03-demos/index.md +++ b/docz/docs/04-getting-started/03-demos/index.md @@ -34,6 +34,7 @@ The demo projects include small runnable examples and short explainers. - [`Chrome / Chromium Extension`](https://github.com/SheetJS/SheetJS/tree/master/demos/chrome/) - [`Google Sheets API`](./gsheet) - [`ExtendScript for Adobe Apps`](./extendscript) +- [`NetSuite SuiteScript`](./netsuite) - [`Excel JavaScript API`](./excel) - [`Headless Browsers`](https://github.com/SheetJS/SheetJS/tree/master/demos/headless/) - [`Other JavaScript Engines`](https://github.com/SheetJS/SheetJS/tree/master/demos/altjs/) diff --git a/docz/docs/06-solutions/01-input.md b/docz/docs/06-solutions/01-input.md index f45eea3..3f6bfd4 100644 --- a/docz/docs/06-solutions/01-input.md +++ b/docz/docs/06-solutions/01-input.md @@ -4,9 +4,13 @@ sidebar_position: 1 # Data Import +import current from '/version.js'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Parsing Workbooks -#### API +### API _Extract data from spreadsheet bytes_ @@ -25,18 +29,31 @@ var workbook = XLSX.readFile(filename, opts); ``` The `readFile` method attempts to read a spreadsheet file at the supplied path. -Browsers generally do not allow reading files in this way (it is deemed a -security risk), and attempts to read files in this way will throw an error. The second `opts` argument is optional. ["Parsing Options"](../api/parse-options) covers the supported properties and behaviors. +:::warning + +Browsers generally do not allow reading files by specifying filename (it is a +security risk), and running `XLSX.readFile` in the browser will throw an error. + +Deno scripts must be invoked with `--allow-read` to read from the filesystem. + + +::: + #### Examples Here are a few common scenarios (click on each subtitle to see the code): -
- Local file in a NodeJS server (click to show) +### Example: Local File + +`XLSX.readFile` supports reading local files in platforms like NodeJS. In other +platforms like React Native, `XLSX.read` should be called with file data. + + + `readFile` uses `fs.readFileSync` under the hood: @@ -58,24 +75,100 @@ const buf = readFileSync("test.xlsx"); const workbook = read(buf); ``` -
- -
- Local file in a Deno application (click to show) + + `readFile` uses `Deno.readFileSync` under the hood: -```js -// @deno-types="https://deno.land/x/sheetjs/types/index.d.ts" -import * as XLSX from 'https://deno.land/x/sheetjs/xlsx.mjs' +
{`\
+// @deno-types="https://cdn.sheetjs.com/xlsx-${current}/package/types/index.d.ts"
+import * as XLSX from 'https://cdn.sheetjs.com/xlsx-${current}/package/xlsx.mjs';
+
+const workbook = XLSX.readFile("test.xlsx");`}
-const workbook = XLSX.readFile("test.xlsx"); -``` Applications reading files must be invoked with the `--allow-read` flag. The [`deno` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/deno/) has more examples -
+ + + +`readFile` can be used in the renderer process: + +```js +/* From the renderer process */ +var XLSX = require("xlsx"); + +var workbook = XLSX.readFile(path); +``` + +Electron APIs have changed over time. The [`electron` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/electron/) +shows a complete example and details the required version-specific settings. + + + + +The [`react` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/react) includes a sample React Native app. + +Since React Native does not provide a way to read files from the filesystem, a +third-party library must be used. The following libraries have been tested: + +- [`react-native-file-access`](https://npm.im/react-native-file-access) + +The `base64` encoding returns strings compatible with the `base64` type: + +```js +import XLSX from "xlsx"; +import { FileSystem } from "react-native-file-access"; + +const b64 = await FileSystem.readFile(path, "base64"); +/* b64 is a base64 string */ +const workbook = XLSX.read(b64, {type: "base64"}); +``` + +- [`react-native-fs`](https://npm.im/react-native-fs) + +The `ascii` encoding returns binary strings compatible with the `binary` type: + +```js +import XLSX from "xlsx"; +import { readFile } from "react-native-fs"; + +const bstr = await readFile(path, "ascii"); +/* bstr is a binary string */ +const workbook = XLSX.read(bstr, {type: "binary"}); +``` + + + + +`readFile` wraps the `File` logic in Photoshop and other ExtendScript targets. +The specified path should be an absolute path: + +```js +#include "xlsx.extendscript.js" + +/* Read test.xlsx from the Documents folder */ +var workbook = XLSX.readFile(Folder.myDocuments + "/test.xlsx"); +``` + +For user-configurable paths, `openDialog` can show a file picker: + +```js +#include "xlsx.extendscript.js" + +/* Ask user to select path */ +var thisFile = File.openDialog("Select a spreadsheet"); +var workbook = XLSX.readFile(thisFile.absoluteURI); +``` + +The [`extendscript` demo](../getting-started/demos/extendscript) includes a more complex example. + + + + + +### Example: User Submissions
User-submitted file in a web page ("Drag-and-Drop") (click to show) @@ -169,6 +262,37 @@ The [`oldie` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/oldie/)
+ +
+ NodeJS Server File Uploads (click to show) + +`read` can accept a NodeJS buffer. `readFile` can read files generated by a +HTTP POST request body parser like [`formidable`](https://npm.im/formidable): + +```js +const XLSX = require("xlsx"); +const http = require("http"); +const formidable = require("formidable"); + +const server = http.createServer((req, res) => { + const form = new formidable.IncomingForm(); + form.parse(req, (err, fields, files) => { + /* grab the first file */ + const f = Object.entries(files)[0][1]; + const path = f.filepath; + const workbook = XLSX.readFile(path); + + /* DO SOMETHING WITH workbook HERE */ + }); +}).listen(process.env.PORT || 7262); +``` + +The [`server` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/server) has more advanced examples. + +
+ +### Example: Remote File +
Fetching a file in the web browser ("Ajax") (click to show) @@ -212,103 +336,6 @@ The [`xhr` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/xhr/) incl
-
- Local file in a PhotoShop or InDesign plugin (click to show) - -`readFile` wraps the `File` logic in Photoshop and other ExtendScript targets. -The specified path should be an absolute path: - -```js -#include "xlsx.extendscript.js" - -/* Read test.xlsx from the Documents folder */ -var workbook = XLSX.readFile(Folder.myDocuments + "/test.xlsx"); -``` - -The [`extendscript` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/extendscript/) includes a more complex example. - -
- -
- Local file in an Electron app (click to show) - -`readFile` can be used in the renderer process: - -```js -/* From the renderer process */ -var XLSX = require("xlsx"); - -var workbook = XLSX.readFile(path); -``` - -Electron APIs have changed over time. The [`electron` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/electron/) -shows a complete example and details the required version-specific settings. - -
- -
- Local file in a mobile app with React Native (click to show) - -The [`react` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/react) includes a sample React Native app. - -Since React Native does not provide a way to read files from the filesystem, a -third-party library must be used. The following libraries have been tested: - -- [`react-native-file-access`](https://npm.im/react-native-file-access) - -The `base64` encoding returns strings compatible with the `base64` type: - -```js -import XLSX from "xlsx"; -import { FileSystem } from "react-native-file-access"; - -const b64 = await FileSystem.readFile(path, "base64"); -/* b64 is a base64 string */ -const workbook = XLSX.read(b64, {type: "base64"}); -``` - -- [`react-native-fs`](https://npm.im/react-native-fs) - -The `ascii` encoding returns binary strings compatible with the `binary` type: - -```js -import XLSX from "xlsx"; -import { readFile } from "react-native-fs"; - -const bstr = await readFile(path, "ascii"); -/* bstr is a binary string */ -const workbook = XLSX.read(bstr, {type: "binary"}); -``` - -
- -
- NodeJS Server File Uploads (click to show) - -`read` can accept a NodeJS buffer. `readFile` can read files generated by a -HTTP POST request body parser like [`formidable`](https://npm.im/formidable): - -```js -const XLSX = require("xlsx"); -const http = require("http"); -const formidable = require("formidable"); - -const server = http.createServer((req, res) => { - const form = new formidable.IncomingForm(); - form.parse(req, (err, fields, files) => { - /* grab the first file */ - const f = Object.entries(files)[0][1]; - const path = f.filepath; - const workbook = XLSX.readFile(path); - - /* DO SOMETHING WITH workbook HERE */ - }); -}).listen(process.env.PORT || 7262); -``` - -The [`server` demo](https://github.com/SheetJS/SheetJS/tree/master/demos/server) has more advanced examples. - -
Download files in a NodeJS process (click to show) @@ -380,6 +407,8 @@ req.end();
+### Example: Readable Streams +
Readable Streams in NodeJS (click to show)