diff --git a/docz/docs/03-demos/06-content.md b/docz/docs/03-demos/06-content.md index 1b3fcca..6e3f420 100644 --- a/docz/docs/03-demos/06-content.md +++ b/docz/docs/03-demos/06-content.md @@ -157,7 +157,7 @@ overridden through a `package.json` override in the latest versions of NodeJS: ::: -
Complete Example (click to show) +
Complete Example (click to show) :::note @@ -364,7 +364,12 @@ text editor and search for "SheetJS" to verify raw HTML was generated:
-## ViteJS +## Bundling Data + +Bundlers can run JS code and process assets during development and during site +builds. Custom plugins can extract data from spreadsheets. + +### ViteJS :::note @@ -460,7 +465,9 @@ ${csv}
-## NextJS +## Site Generators + +### NextJS :::note @@ -516,7 +523,162 @@ export async function getServerSideProps() { ::: -### Strategies +#### Demo + +
Complete Example (click to show) + +0) Disable NextJS telemetry: + +```js +npx next telemetry disable +``` + +Confirm it is disabled by running + +```js +npx next telemetry status +``` + +1) Set up folder structure. At the end, a `pages` folder with a `sheets` + subfolder must be created. On Linux or MacOS or WSL: + +```bash +mkdir -p pages/sheets/ +``` + +2) Download the [test file](pathname:///next/sheetjs.xlsx) and place in the + project root. On Linux or MacOS or WSL: + +```bash +curl -LO https://docs.sheetjs.com/next/sheetjs.xlsx +``` + +3) Install dependencies: + +```bash +npm i --save https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz next@12.2.5 +``` + +4) Download test scripts: + +Download and place the following scripts in the `pages` subfolder: + +- [`index.js`](pathname:///next/index.js) +- [`getServerSideProps.js`](pathname:///next/getServerSideProps.js) +- [`getStaticPaths.js`](pathname:///next/getStaticPaths.js) +- [`getStaticProps.js`](pathname:///next/getStaticProps.js) + +Download [`[id].js`](pathname:///next/%5Bid%5D.js) and place in the +`pages/sheets` subfolder. + +:::caution Percent-Encoding in the script name + +The `[id].js` script must have the literal square brackets in the name. If your +browser saved the file to `%5Bid%5D.js`. rename the file. + +::: + +On Linux or MacOS or WSL: + +```bash +cd pages +curl -LO https://docs.sheetjs.com/next/index.js +curl -LO https://docs.sheetjs.com/next/getServerSideProps.js +curl -LO https://docs.sheetjs.com/next/getStaticPaths.js +curl -LO https://docs.sheetjs.com/next/getStaticProps.js +cd sheets +curl -LOg 'https://docs.sheetjs.com/next/[id].js' +cd ../.. +``` + +5) Test the deployment: + +```bash +npx next@12.2.5 +``` + +Open a web browser and access: + +- http://localhost:3000 landing page +- http://localhost:3000/getStaticProps shows data from the first sheet +- http://localhost:3000/getServerSideProps shows data from the first sheet +- http://localhost:3000/getStaticPaths shows a list (3 sheets) + +The individual worksheets are available at + +- http://localhost:3000/sheets/0 +- http://localhost:3000/sheets/1 +- http://localhost:3000/sheets/2 + +6) Stop the server and run a production build: + +```bash +npx next@12.2.5 build +``` + +The final output will show a list of the routes and types: + +``` +Route (pages) Size First Load JS +┌ ○ / 551 B 81.7 kB +├ ○ /404 194 B 77.2 kB +├ λ /getServerSideProps 602 B 81.7 kB +├ ● /getStaticPaths 2.7 kB 83.8 kB +├ ● /getStaticProps 600 B 81.7 kB +└ ● /sheets/[id] (312 ms) 580 B 81.7 kB + ├ /sheets/0 + ├ /sheets/1 + └ /sheets/2 +``` + +As explained in the summary, the `/getStaticPaths` and `/getStaticProps` routes +are completely static. 3 `/sheets/#` pages were generated, corresponding to 3 +worksheets in the file. `/getServerSideProps` is server-rendered. + +7) Try to build a static site: + +```bash +npx next@12.2.5 export +``` + +:::note The static export will fail! + +A static page cannot be generated at this point because `/getServerSideProps` +is still server-rendered. + +::: + +8) Remove `pages/getServerSideProps.js` and rebuild with `npx next@12.2.5 build` + +Inspecting the output, there should be no lines with the `λ` symbol: + +``` +Route (pages) Size First Load JS +┌ ○ / 551 B 81.7 kB +├ ○ /404 194 B 77.2 kB +├ ● /getStaticPaths 2.7 kB 83.8 kB +├ ● /getStaticProps 600 B 81.7 kB +└ ● /sheets/[id] (312 ms) 580 B 81.7 kB + ├ /sheets/0 + ├ /sheets/1 + └ /sheets/2 +``` + +9) Generate the static site: + +```bash +npx next@12.2.5 export +``` + +The static site will be written to the `out` subfolder, which can be hosted with + +```bash +npx http-server out +``` + +The command will start a local HTTP server on port 8080. + +
#### "Static Site Generation" using `getStaticProps` @@ -605,174 +767,180 @@ export async function getServerSideProps() { }; ``` -### Demo -
Complete Example (click to show) - -0) Disable NextJS telemetry: - -```js -npx next telemetry disable -``` - -Confirm it is disabled by running - -```js -npx next telemetry status -``` - -1) Set up folder structure. At the end, a `pages` folder with a `sheets` - subfolder must be created. On Linux or MacOS or WSL: - -```bash -mkdir -p pages/sheets/ -``` - -2) Download the [test file](pathname:///next/sheetjs.xlsx) and place in the - project root. On Linux or MacOS or WSL: - -```bash -curl -LO https://docs.sheetjs.com/next/sheetjs.xlsx -``` - -3) Install dependencies: - -```bash -npm i --save https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz next -``` - -4) Download test scripts: - -Download and place the following scripts in the `pages` subfolder: - -- [`index.js`](pathname:///next/index.js) -- [`getServerSideProps.js`](pathname:///next/getServerSideProps.js) -- [`getStaticPaths.js`](pathname:///next/getStaticPaths.js) -- [`getStaticProps.js`](pathname:///next/getStaticProps.js) - -Download [`[id].js`](pathname:///next/%5Bid%5D.js) and place in the -`pages/sheets` subfolder. - -:::caution Percent-Encoding in the script name - -The `[id].js` script must have the literal square brackets in the name. If your -browser saved the file to `%5Bid%5D.js`. rename the file. - -::: - -On Linux or MacOS or WSL: - -```bash -cd pages -curl -LO https://docs.sheetjs.com/next/index.js -curl -LO https://docs.sheetjs.com/next/getServerSideProps.js -curl -LO https://docs.sheetjs.com/next/getStaticPaths.js -curl -LO https://docs.sheetjs.com/next/getStaticProps.js -cd sheets -curl -LOg 'https://docs.sheetjs.com/next/[id].js' -cd ../.. -``` - -5) Test the deployment: - -```bash -npx next -``` - -Open a web browser and access: - -- http://localhost:3000 landing page -- http://localhost:3000/getStaticProps shows data from the first sheet -- http://localhost:3000/getServerSideProps shows data from the first sheet -- http://localhost:3000/getStaticPaths shows a list (3 sheets) - -The individual worksheets are available at - -- http://localhost:3000/sheets/0 -- http://localhost:3000/sheets/1 -- http://localhost:3000/sheets/2 - -6) Stop the server and run a production build: - -```bash -npx next build -``` - -The final output will show a list of the routes and types: - -``` -Route (pages) Size First Load JS -┌ ○ / 551 B 81.7 kB -├ ○ /404 194 B 77.2 kB -├ λ /getServerSideProps 602 B 81.7 kB -├ ● /getStaticPaths 2.7 kB 83.8 kB -├ ● /getStaticProps 600 B 81.7 kB -└ ● /sheets/[id] (312 ms) 580 B 81.7 kB - ├ /sheets/0 - ├ /sheets/1 - └ /sheets/2 -``` - -As explained in the summary, the `/getStaticPaths` and `/getStaticProps` routes -are completely static. 3 `/sheets/#` pages were generated, corresponding to 3 -worksheets in the file. `/getServerSideProps` is server-rendered. - -7) Try to build a static site: - -```bash -npx next export -``` - -:::note The static export will fail! - -A static page cannot be generated at this point because `/getServerSideProps` -is still server-rendered. - -::: - -8) Remove `pages/getServerSideProps.js` and rebuild with `npx next build`. - -Inspecting the output, there should be no lines with the `λ` symbol: - -``` -Route (pages) Size First Load JS -┌ ○ / 551 B 81.7 kB -├ ○ /404 194 B 77.2 kB -├ ● /getStaticPaths 2.7 kB 83.8 kB -├ ● /getStaticProps 600 B 81.7 kB -└ ● /sheets/[id] (312 ms) 580 B 81.7 kB - ├ /sheets/0 - ├ /sheets/1 - └ /sheets/2 -``` - -9) Generate the static site: - -```bash -npx next export -``` - -The static site will be written to the `out` subfolder, which can be hosted with - -```bash -npx http-server out -``` - -The command will start a local HTTP server on port 8080. - -
- -## NuxtJS +### NuxtJS `@nuxt/content` is a file-based CMS for Nuxt, enabling static-site generation and on-demand server rendering powered by spreadsheets. :::note -This demo was tested on 2022 November 07 against Nuxt Content `v1.15.1`. +This demo was tested on 2022 November 18 against Nuxt Content `v1.15.1`. ::: +#### Nuxt Content Demo + +
Complete Example (click to show) + +:::note + +The project was generated using `create-nuxt-app v4.0.0`. The generated project +used Nuxt `v2.15.8` and Nuxt Content `v1.15.1`. + +::: + +1) Create a stock app: + +```bash +npx create-nuxt-app@4.0.0 SheetJSNuxt +``` + +When prompted, enter the following options: + +- `Project name`: press Enter (use default `SheetJSNuxt`) +- `Programming language`: press Down Arrow (`TypeScript` selected) then Enter +- `Package manager`: select `Npm` and press Enter +- `UI framework`: select `None` and press Enter +- `Nuxt.js modules`: scroll to `Content`, select with Space, then press Enter +- `Linting tools`: press Enter (do not select any Linting tools) +- `Testing framework`: select `None` and press Enter +- `Rendering mode`: select `Universal (SSR / SSG)` and press Enter +- `Deployment target`: select `Static (Static/Jamstack hosting)` and press Enter +- `Development tools`: press Enter (do not select any Development tools) +- `What is your GitHub username?`: press Enter +- `Version control system`: select `None` + +The project will be configured and modules will be installed. + +2) Install the SheetJS library and start the server: + +```bash +cd SheetJSNuxt +npm i --save https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz +npm run dev +``` + +When the build finishes, the terminal will display a URL like: + +``` +ℹ Listening on: http://localhost:64688/ +``` + +The server is listening on that URL. Open the link in a web browser. + +3) Download and move to the `content` folder. + +```bash +curl -LO https://sheetjs.com/pres.xlsx +mv pres.xlsx content/ +``` + +4) Modify `nuxt.config.js` as follows: + +- Add the following to the top of the script: + +```js +import { readFile, utils } from 'xlsx'; + +// This will be called when the files change +const parseSheet = (file, { path }) => { + // `path` is a path that can be read with `XLSX.readFile` + const wb = readFile(path); + const o = wb.SheetNames.map(name => ({ name, data: utils.sheet_to_json(wb.Sheets[name])})); + return { data: o }; +} +``` + +- Look for the exported object. There should be a `content` property: + +```js + // Content module configuration: https://go.nuxtjs.dev/config-content + content: {}, +``` + +Replace the property with the following definition: + +```js + // content.extendParser allows us to hook into the parsing step + content: { + extendParser: { + // the keys are the extensions that will be matched. The "." is required + ".numbers": parseSheet, + ".xlsx": parseSheet, + ".xls": parseSheet, + // can add other extensions like ".fods" as desired + } + }, +``` + +(If the property is missing, add it to the end of the exported object) + +5) Replace `pages/index.vue` with the following: + +```html + + + + +``` + +The browser should refresh to show the contents of the spreadsheet. If it does +not, click Refresh manually or open a new browser window. + +![Nuxt Demo end of step 5](pathname:///nuxt/nuxt5.png) + +6) To verify that hot loading works, open `pres.xlsx` from the `content` folder +in Excel. Add a new row to the bottom and save the file: + +![Adding a new line to `pres.xlsx`](pathname:///nuxt/nuxl6.png) + +The server terminal window should show a line like: + +``` +ℹ Updated ./content/pres.xlsx @nuxt/content 05:43:37 +``` + +The page should automatically refresh with the new content: + +![Nuxt Demo end of step 6](pathname:///nuxt/nuxt6.png) + +7) Stop the server (press `CTRL+C` in the terminal window) and run + +```bash +npm run generate +``` + +This will create a static site in the `dist` folder, which can be served with: + +```bash +npx http-server dist +``` + +Accessing the page http://localhost:8080 will show the page contents. Verifying +the static nature is trivial: make another change in Excel and save. The page +will not change. + +
+ #### nuxt.config.js configuration Through an override in `nuxt.config.js`, Nuxt Content will use custom parsers. @@ -839,128 +1007,3 @@ neatly with nested `v-for`: ``` - -### Nuxt Content Demo - -
Complete Example (click to show) - -:::note - -This was tested against `create-nuxt-app v4.0.0` on 2022 November 07. - -The generated project used Nuxt `v2.15.8` and Nuxt Content `v1.15.1`. - -::: - -1) Create a stock app: - -```bash -npx create-nuxt-app@4.0.0 SheetJSNuxt -``` - -When prompted, enter the following options: - -- `Project name`: press Enter (use default `SheetJSNuxt`) -- `Programming language`: press Down Arrow (`TypeScript` selected) then Enter -- `Package manager`: select `Npm` and press Enter -- `UI framework`: select `None` and press Enter -- `Nuxt.js modules`: scroll to `Content`, select with Space, then press Enter -- `Linting tools`: press Enter (do not select any Linting tools) -- `Testing framework`: select `None` and press Enter -- `Rendering mode`: select `Universal (SSR / SSG)` and press Enter -- `Deployment target`: select `Static (Static/Jamstack hosting)` and press Enter -- `Development tools`: press Enter (do not select any Development tools) -- `What is your GitHub username?`: press Enter -- `Version control system`: select `None` - -The project will be configured and modules will be installed. - -2) Install the SheetJS library and start the server: - -```bash -cd SheetJSNuxt -npm i --save https://cdn.sheetjs.com/xlsx-latest/xlsx-latest.tgz -npm run dev -``` - -When the build finishes, the terminal will display a URL like: - -``` -ℹ Listening on: http://localhost:64688/ -``` - -The server is listening on that URL. Open the link in a web browser. - -3) Download and move to the `content` folder. - -```bash -curl -LO https://sheetjs.com/pres.xlsx -mv pres.xlsx content/ -``` - -4) Modify `nuxt.config.js` as described [earlier](#nuxtconfigjs-configuration) - -5) Replace `pages/index.vue` with the following: - -```html - - - - -``` - -The browser should refresh to show the contents of the spreadsheet. If it does -not, click Refresh manually or open a new browser window. - -![Nuxt Demo end of step 5](pathname:///nuxt/nuxt5.png) - -6) To verify that hot loading works, open `pres.xlsx` from the `content` folder -in Excel. Add a new row to the bottom and save the file: - -![Adding a new line to `pres.xlsx`](pathname:///nuxt/nuxl6.png) - -The server terminal window should show a line like: - -``` -ℹ Updated ./content/pres.xlsx @nuxt/content 05:43:37 -``` - -The page should automatically refresh with the new content: - -![Nuxt Demo end of step 6](pathname:///nuxt/nuxt6.png) - -7) Stop the server (press `CTRL+C` in the terminal window) and run - -```bash -npm run generate -``` - -This will create a static site in the `dist` folder, which can be served with: - -```bash -npx http-server dist -``` - -Accessing the page http://localhost:8080 will show the page contents. Verifying -the static nature is trivial: make another change in Excel and save. The page -will not change. - -
diff --git a/docz/docs/03-demos/08-stream.md b/docz/docs/03-demos/08-stream.md index f8ee8b2..5efb479 100644 --- a/docz/docs/03-demos/08-stream.md +++ b/docz/docs/03-demos/08-stream.md @@ -15,7 +15,7 @@ worksheet objects that use arrays of arrays under the hood: ```js var dense_wb = XLSX.read(ab, {dense: true}); -var dense_sheet = XLSX.utils.aoa_to_sheet(aoa); +var dense_sheet = XLSX.utils.aoa_to_sheet(aoa, {dense: true}); ```
Historical Note (click to show) diff --git a/docz/docs/03-demos/23-netsuite.md b/docz/docs/03-demos/23-netsuite.md index d590212..d1cdd8c 100644 --- a/docz/docs/03-demos/23-netsuite.md +++ b/docz/docs/03-demos/23-netsuite.md @@ -15,7 +15,7 @@ perused before reading this demo: The library plays nice with each script type, including RESTlets and Suitelets. -## Loading the SheetJS Standalone Script +## Installation [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