diff --git a/docz/docs/03-demos/04-static/11-svelte.md b/docz/docs/03-demos/04-static/11-svelte.md index 9879eea..75417b7 100644 --- a/docz/docs/03-demos/04-static/11-svelte.md +++ b/docz/docs/03-demos/04-static/11-svelte.md @@ -1,25 +1,35 @@ --- title: SvelteKit +sidebar_label: SvelteKit +description: Make static websites from spreadsheets using SvelteKit. Seamlessly integrate data into your website using SheetJS. Rapidly develop web apps powered by data in Excel. pagination_prev: demos/net/index pagination_next: demos/mobile/index --- +# Supercharge SvelteKit Apps with Spreadsheets + import current from '/version.js'; import CodeBlock from '@theme/CodeBlock'; -:::note +[SvelteKit](https://kit.svelte.dev/) is a framework for generating static sites. +It leverages modern technologies including ViteJS and SvelteJS[^1] -This demo covers SvelteKit. The [Svelte demo](/docs/demos/frontend/svelte) -covers general client-side strategies. +[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing +data from spreadsheets. -This demo uses ["Base64 Loader"](/docs/demos/static/vitejs#base64-loader) -from the ViteJS demo. +This demo uses SvelteKit and SheetJS to pull data from a spreadsheet and display +the content in an HTML table. We'll explore how to use a plugin to pull raw data +from files and how to organize page scripts to process the files at compile time. + +The ["Complete Example"](#complete-example) section includes a complete website +powered by an XLSX spreadsheet. + +:::note pass + +The [Svelte demo](/docs/demos/frontend/svelte) covers general client-side usage. ::: -SvelteKit projects use ViteJS under the hood. They expose the `vite.config.js` -script. The [ViteJS demo](/docs/demos/static/vitejs) examples work as expected! - The following diagram depicts the workbook waltz: ```mermaid @@ -45,7 +55,11 @@ For static site generation, `@sveltejs/adapter-static` must be used. ### Loader -:::note +SvelteKit projects use ViteJS under the hood. They expose the `vite.config.js` +script. The "Base64 Loader" from the ViteJS demo[^2] can pull data from files +into Base64 strings for processing in `+page.server.js` scripts. + +:::note pass The ViteJS demo used the query `?b64` to identify files. To play nice with SvelteKit, this demo matches the file extensions directly. @@ -53,7 +67,7 @@ SvelteKit, this demo matches the file extensions directly. ::: The loader should be added to `vite.config.js`. The code is nearly identical to -the ["Base64 Loader" ViteJS example.](/docs/demos/static/vitejs#base64-loader) +the "Base64 Loader" ViteJS example. ```js title="vite.config.js" import { sveltekit } from '@sveltejs/kit/vite'; @@ -95,7 +109,8 @@ declare global { ### Data Processing -For static sites, SheetJS operations should be run in `+page.server.js` . +For static sites, SheetJS operations should be run in `+page.server.js`[^3]. The +script must include `export const prerender = true`[^4]. Assuming `pres.xlsx` is stored in the `data` directory from the project root, the relative import @@ -105,9 +120,12 @@ import b64 from "../../data/pres.xlsx" ``` will return a Base64 string which can be parsed in the script. The workbook -object can be post-processed using utility functions. The following example -uses `sheet_to_json` to generate arrays of row objects for each worksheet. The -data presented to the page will be an object whose keys are worksheet names: +object can be post-processed using utility functions. + +The following example uses the SheetJS `read` method[^5] to parse spreadsheet +files and the `sheet_to_json` method[^6] to generate arrays of row objects for +each worksheet. The data presented to the page will be an object whose keys are +worksheet names: ```js title="src/routes/+page.server.js" import b64 from "../../data/pres.xlsx"; @@ -157,7 +175,7 @@ a simple HTML table without any reference to the existing spreadsheet file! :::note -This demo was tested on 2023 April 30 using SvelteKit `1.15.9` +This demo was tested on 2023 July 12 using SvelteKit `1.22.2` and Svelte `4.0.5` ::: @@ -167,8 +185,6 @@ This demo was tested on 2023 April 30 using SvelteKit `1.15.9` ```bash npm create svelte@latest sheetjs-svelte -cd sheetjs-svelte -npm i ``` When prompted: @@ -177,7 +193,14 @@ When prompted: - `Add type checking with TypeScript?` select `Yes, using JavaScript with JSDoc` - `Select additional options` press Enter (do not select options) -2) Fetch the example file [`pres.xlsx`](https://sheetjs.com/pres.xlsx) and move +2) Enter the project folder and install dependencies: + +```bash +cd sheetjs-svelte +npm i +``` + +3) Fetch the example file [`pres.xlsx`](https://sheetjs.com/pres.xlsx) and move to a `data` subdirectory in the root of the project: ```bash @@ -185,29 +208,30 @@ mkdir -p data curl -Lo data/pres.xlsx https://sheetjs.com/pres.xlsx ``` -3) Install the SheetJS library: +4) Install the SheetJS library: {`\ npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`} -4) Replace the contents of `vite.config.js` with the contents of the code block +5) Replace the contents of `vite.config.js` with the contents of the code block named [`vite.config.js` in the "Loader" section](#loader) -5) Append the lines from [`src/app.d.ts` snippet in the "Types" section](#types) +6) Append the lines from [`src/app.d.ts` snippet in the "Types" section](#types) to the `src/app.d.ts` file. -6) Replace the contents of `src/routes/+page.server.ts` with the contents of the -code block named [`src/routes/+page.server.ts` in "Data Processing"](#data-processing) +7) Replace the contents of `src/routes/+page.server.ts` with the contents of the +code block named [`src/routes/+page.server.ts` in "Data Processing"](#data-processing). +If the file does not exist, create a new file. -7) Replace the contents of `src/routes/+page.svelte` with the contents of the +8) Replace the contents of `src/routes/+page.svelte` with the contents of the code block named [`src/routes/+page.svelte` in "Data Rendering"](#data-rendering) ### Live Reload -8) Open `data/pres.xlsx` in a spreadsheet editor like Apple Numbers or Excel. +9) Open `data/pres.xlsx` in a spreadsheet editor like Apple Numbers or Excel. -9) Start the development server: +10) Start the development server: ```bash npm run dev @@ -216,29 +240,48 @@ npm run dev Open the displayed URL (typically `http://localhost:5173`) in a web browser and observe that the data from the spreadsheet is displayed in the page. -10) In the spreadsheet, set cell A7 to `SheetJS Dev` and cell B7 to `47`. Save +11) In the spreadsheet, set cell A7 to `SheetJS Dev` and cell B7 to `47`. Save the file. After saving, the browser should automatically refresh with new data. ### Static Site -11) Stop the development server and install the static adapter: +12) Stop the development server and install the static adapter: ```bash npm i --save @sveltejs/adapter-static ``` -12) Edit `svelte.config.js` to use the new adapter: +13) Edit `svelte.config.js` to use the new adapter: ```diff title="svelte.config.js" -import adapter from '@sveltejs/adapter-auto'; +import adapter from '@sveltejs/adapter-static'; ``` -13) Build the static site: +14) Build the static site: ```bash npm run build ``` -14) Open a web browser and access the displayed URL (`http://localhost:8080`). -View the page source and confirm that the raw HTML table includes the data. \ No newline at end of file +15) Start a local web server that will host the production build: + +```bash +npx -y http-server build +``` + +16) Open a web browser and access the displayed URL (`http://localhost:8080`). +View the page source and confirm that the raw HTML table includes the data. + +Searching for `Bill Clinton` should reveal the following row: + +```html +Bill Clinton 42 +``` + +[^1]: See ["SvelteKit vs Svelte"](https://kit.svelte.dev/docs/introduction#sveltekit-vs-svelte) in the SvelteKit documentation. +[^2]: See ["Base64 Plugin" in the ViteJS demo](/docs/demos/static/vitejs#base64-plugin) +[^3]: See ["Universal vs server"](https://kit.svelte.dev/docs/load#universal-vs-server) in the SvelteKit documentation. +[^4]: See ["prerender"](https://kit.svelte.dev/docs/page-options#prerender) in the SvelteKit documentation. +[^5]: See [`read` in "Reading Files"](/docs/api/parse-options) +[^6]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output) diff --git a/docz/docs/07-csf/07-features/02-hyperlinks.md b/docz/docs/07-csf/07-features/02-hyperlinks.md index 4652935..7429627 100644 --- a/docz/docs/07-csf/07-features/02-hyperlinks.md +++ b/docz/docs/07-csf/07-features/02-hyperlinks.md @@ -7,6 +7,12 @@ sidebar_position: 2
File Format Support (click to show) +Traditional spreadsheet software, including Excel, support "Cell Links". The +entire cell text is clickable. + +Modern spreadsheet software, including Numbers, support "Span Links". Links are +applied to text fragments within the cell content. This mirrors HTML semantics. + | Formats | Link | Tooltip | Link Type | |:------------------|:-----:|:-------:|:----------| | XLSX / XLSM | ✔ | ✔ | Cell Link | @@ -29,14 +35,14 @@ Hyperlinks are stored in the `l` key of cell objects. The `Target` field of the hyperlink object is the target of the link, including the URI fragment. Tooltips are stored in the `Tooltip` field and are displayed when hovering over the text. -For example, the following snippet creates a link from cell `A3` to +For example, the following snippet creates a link from cell `A1` to with the tip `"Find us @ SheetJS.com!"`: ```js ws["A1"].l = { Target: "https://sheetjs.com", Tooltip: "Find us @ SheetJS.com!" }; ``` -:::note +:::note pass Following traditional software, hyperlinks are applied to entire cell objects. Some formats (including HTML) attach links to text spans. The parsers apply the @@ -44,7 +50,7 @@ first link to the entire cell. Writers apply links to the entire cell text. ::: -:::caution +:::caution pass Excel does not automatically style hyperlinks. They will be displayed using the default cell style. @@ -142,7 +148,7 @@ ws["B3"].l = { Target: "SheetJS.xlsb" }; /* Link to SheetJS.xlsb */ ws["B4"].l = { Target: "../SheetJS.xlsm" }; /* Link to ../SheetJS.xlsm */ ``` -:::caution +:::caution pass Relative Paths have undefined behavior in the SpreadsheetML 2003 format. Excel 2019 will treat a `..\` parent mark as two levels up. diff --git a/docz/docs/09-miscellany/05-contributing.md b/docz/docs/09-miscellany/05-contributing.md index 39c6d56..7014efb 100644 --- a/docz/docs/09-miscellany/05-contributing.md +++ b/docz/docs/09-miscellany/05-contributing.md @@ -39,7 +39,7 @@ These instructions were tested on the following platforms: | Platform | Test Date | |:------------------------------|:-----------| -| Linux (Steam Deck Holo 3.4.6) | 2023-04-04 | +| Linux (Steam Deck Holo 3.4.8) | 2023-07-12 | | Linux (Ubuntu 18.04 aarch64) | 2023-04-13 | | MacOS 10.13 (x64) | 2023-04-04 | | MacOS 13.0 (arm64) | 2023-04-13 |