From fa5ff21a8ec80b55338ba5ec62f9b1d4b843352e Mon Sep 17 00:00:00 2001 From: SheetJS Date: Tue, 4 Oct 2022 16:37:38 -0400 Subject: [PATCH] lume --- .spelling | 1 + .../01-installation/06-deno.md | 9 + docz/docs/03-demos/06-content.md | 239 ++++++------------ docz/docs/03-demos/41-nosql.md | 2 +- docz/docs/06-solutions/05-output.md | 2 +- docz/docs/07-csf/03-sheet.md | 1 + docz/docs/07-csf/07-features/01-formulae.md | 19 +- docz/docs/07-csf/07-features/02-hyperlinks.md | 122 +++++++-- docz/docs/07-csf/07-features/index.md | 18 +- docz/docs/09-miscellany/02-errors.md | 4 +- docz/docs/09-miscellany/03-source.md | 12 + docz/docs/09-miscellany/07-license.md | 25 +- docz/docusaurus.config.js | 4 +- 13 files changed, 253 insertions(+), 205 deletions(-) create mode 100644 docz/docs/09-miscellany/03-source.md diff --git a/.spelling b/.spelling index 0c470f28..a328cadf 100644 --- a/.spelling +++ b/.spelling @@ -12,6 +12,7 @@ api csf # Excel-related terms +A1 A1-Style AutoFilter BIFF12 diff --git a/docz/docs/02-getting-started/01-installation/06-deno.md b/docz/docs/02-getting-started/01-installation/06-deno.md index 725b35ad..a8734161 100644 --- a/docz/docs/02-getting-started/01-installation/06-deno.md +++ b/docz/docs/02-getting-started/01-installation/06-deno.md @@ -10,6 +10,15 @@ import current from '/version.js'; # Deno +[Deno](https://deno.land/) is a JavaScript runtime powered by V8. + +:::caution Deno support is considered experimental. + +Great open source software grows with user tests and reports. Any issues should +be reported to the Deno project for further diagnosis. + +::: + Each standalone release script is available at . Using the URL imports, `deno run` will automatically download scripts and types: diff --git a/docz/docs/03-demos/06-content.md b/docz/docs/03-demos/06-content.md index cb18ae78..87960fcf 100644 --- a/docz/docs/03-demos/06-content.md +++ b/docz/docs/03-demos/06-content.md @@ -6,6 +6,88 @@ With the advent of server-side frameworks and content management systems, it is possible to build sites whose source of truth is a spreadsheet! This demo explores a number of approaches. +## Lume + +[Lume](https://lume.land) is a static site generator for the Deno platform. + +The official [Sheets plugin](https://lume.land/plugins/sheets/) uses SheetJS +to load data from spreadsheets. + +### Lume Demo + +:::note + +This was tested against `lume v1.12.0` on 2022 October 4. + +::: + +
Complete Example (click to show) + +1) Create a stock site: + +```bash +mkdir sheetjs-lume +cd sheetjs-lume +deno run -A https://deno.land/x/lume/init.ts +``` + +When prompted, enter the following options: + +- `Use TypeScript for the configuration file`: press Enter (use default `N`) +- `Do you want to use plugins`: type `sheets` and press Enter + +The project will be configured and modules will be installed. + +2) Download and place in a `_data` folder: + +```bash +mkdir _data +curl -LO https://sheetjs.com/pres.numbers +mv pres.numbers _data +``` + +3) Create a `index.njk` file that references the file. Since the file is + `pres.numbers`, the parameter name is `pres`: + +```liquid title="index.njk" +

Presidents

+ + + {% for row in pres %}{% if (loop.index >= 1) %} + + + + + {% endif %}{% endfor %} + +
NameIndex
{{ row.Name }}{{ row.Index }}
+``` + +4) Run the development server: + +```bash +deno task lume --serve +``` + +To verify it works, access http://localhost:3000 from your web browser. +Adding a new row and saving `pres.numbers` should refresh the data + +5) Stop the server (press `CTRL+C` in the terminal window) and run + +```bash +deno task lume +``` + +This will create a static site in the `_site` folder, which can be served with: + +```bash +npx http-server _site +``` + +Accessing the page http://localhost:8080 will show the page contents. + +
+ ## GatsbyJS [`gatsby-transformer-excel`](https://www.gatsbyjs.com/plugins/gatsby-transformer-excel/) @@ -513,160 +595,3 @@ the static nature is trivial: make another change in Excel and save. The page will not change. - -## Lume - -Lume is a static site generator for the Deno platform. - -`lume#loadData` can add custom loaders for data. The loader method receives a -path to the file, which can be read with `XLSX.readFile`. This should be added -to `_config.js`, like in the example below: - -```js title="_config.js" -import lume from "lume/mod.ts"; -import { readFile, utils } from 'https://cdn.sheetjs.com/xlsx-latest/package/xlsx.mjs'; - -function wbLoader(path) { - const wb = readFile(path); - const res = wb.SheetNames.map(n => ({ - name: n, - data: utils.sheet_to_json(wb.Sheets[n]) - })); - return { content: res }; -} - -const site = lume(); -const exts = [".xlsx", ".numbers", /* ... other supported extensions */]; -// highlight-next-line -site.loadData(exts, wbLoader); - -export default site; -``` - -The actual spreadsheets should be placed in the `_data` subfolder. - -The variable name is the stem of the filename (`sheetjs` if `sheetjs.xlsx` or -`sheetjs.numbers` exists). A Nunjucks or JSX template can loop through the -worksheets and the data rows. The example assumes each worksheet has a `name` and `index` column: - -```jsx title="index.jsx" -export default ({sheetjs}) => { - return (<>{(sheetjs).map(sheet => (<> -

{sheet.name}

- - {sheet.data.map(row => ( - - - ))} -
NameIndex
{row.name}{row.index}
- ))}); -}; -``` - -### Lume Demo - -
Complete Example (click to show) - -:::note - -This was tested against `lume v1.10.4` on 2022 August 25. - -::: - -1) Create a stock site: - -```bash -mkdir sheetjs-lume -cd sheetjs-lume -deno run -A https://deno.land/x/lume/init.ts -``` - -When prompted, enter the following options: - -- `Use TypeScript for the configuration file`: press Enter (use default `N`) -- `Do you want to use plugins`: type `jsx` and press Enter - -The project will be configured and modules will be installed. - -2) Make the following highlighted changes to `_config.js`: - -```js title="_config.js" -import lume from "lume/mod.ts"; -import jsx from "lume/plugins/jsx.ts"; - -// highlight-start -import { readFile, utils } from 'https://cdn.sheetjs.com/xlsx-latest/package/xlsx.mjs'; - -function wbLoader(path) { - const wb = readFile(path); - const res = wb.SheetNames.map(n => ({ - name: n, - data: utils.sheet_to_json(wb.Sheets[n]) - })); - return { content: res }; -} -// highlight-end - -const site = lume(); - -site.use(jsx()); - -// highlight-start -const exts = [".xlsx", ".numbers", /* ... other supported extensions */]; -site.loadData(exts, wbLoader); -// highlight-end - -export default site; -``` - -This instructs Lume to watch for and load `.xlsx` and `.numbers` spreadsheets - -3) Download and place in a `_data` folder: - -```bash -mkdir _data -curl -LO https://sheetjs.com/pres.numbers -mv pres.numbers _data -``` - -4) Create a `index.jsx` file that references the file. Since the file is - `pres.numbers`, the parameter name is `pres`: - -```jsx title="index.jsx" -export default ({pres}) => { - return (<>{(pres).map(sheet => (<> -

{sheet.name}

- - {sheet.data.map(row => ( - - - ))} -
NameIndex
{row.Name}{row.Index}
- ))}); -}; -``` - -5) Run the development server: - -```bash -deno task lume --serve -``` - -To verify it works, access http://localhost:3000 from your web browser. -Adding a new row and saving `pres.numbers` should refresh the data - -6) Stop the server (press `CTRL+C` in the terminal window) and run - -```bash -deno task lume -``` - -This will create a static site in the `_site` folder, which can be served with: - -```bash -npx http-server _serve -``` - -Accessing the page http://localhost:8080 will show the page contents. - -
\ No newline at end of file diff --git a/docz/docs/03-demos/41-nosql.md b/docz/docs/03-demos/41-nosql.md index f47bddb8..3f66a4ff 100644 --- a/docz/docs/03-demos/41-nosql.md +++ b/docz/docs/03-demos/41-nosql.md @@ -219,7 +219,7 @@ includes an example of constructing a simple array. function export_pouchdb_to_xlsx(db) { /* fetch all rows, including the underlying data */ db.allDocs({include_docs: true}, function(err, doc) { - + /* pull the individual data rows */ const aoo = doc.rows.map(r => { /* `rest` will include every field from `r` except for _id and _rev */ diff --git a/docz/docs/06-solutions/05-output.md b/docz/docs/06-solutions/05-output.md index 5855b875..1aa9abaa 100644 --- a/docz/docs/06-solutions/05-output.md +++ b/docz/docs/06-solutions/05-output.md @@ -890,4 +890,4 @@ rd.resume(); - pipes write streams to nodejs response. + pipes write streams to nodejs response. diff --git a/docz/docs/07-csf/03-sheet.md b/docz/docs/07-csf/03-sheet.md index 54887d48..4753134f 100644 --- a/docz/docs/07-csf/03-sheet.md +++ b/docz/docs/07-csf/03-sheet.md @@ -113,6 +113,7 @@ In addition to the aforementioned sheet keys, worksheets also add: | `pivotTables` | Use PivotTable reports | disabled | | `objects` | Edit objects | enabled | | `scenarios` | Edit scenarios | enabled | + - `ws['!autofilter']`: AutoFilter object following the schema: diff --git a/docz/docs/07-csf/07-features/01-formulae.md b/docz/docs/07-csf/07-features/01-formulae.md index b5f7bb27..2d465ab5 100644 --- a/docz/docs/07-csf/07-features/01-formulae.md +++ b/docz/docs/07-csf/07-features/01-formulae.md @@ -16,14 +16,17 @@ while the writer will translate from A1-Style strings to the file format. |:------------------|:-----:|:-----:|:-----:|:-------:|:-----------------------| | XLSX / XLSM | ✔ | ✔ | ✔ | ✔ | A1-Style strings | | XLSB | ✔ | | ✔ | ✔ | BIFF parsed tokens | -| XLS | ✔ | | ✔ | | BIFF parsed tokens | -| XLML | ✔ | ✔ | ✔ | | RC-style strings | -| SYLK | ✔ | ✔ | | | `A1`/RC-style strings | -| CSV / TXT | ✔ | ✔ | | | A1-Style strings | -| ODS / FODS / UOS | ✔ | ✔ | | | OpenFormula strings | -| WK\* | ✔ | | | | Lotus parsed tokens | -| WQ\* / WB\* / QPW | | | | | Quattro Pro tokens | -| NUMBERS | | | | | Numbers parsed tokens | +| XLS | ✔ | | ✔ | * | BIFF parsed tokens | +| XLML | ✔ | ✔ | ✔ | * | RC-style strings | +| SYLK | ✔ | ✔ | | * | A1/RC-style strings | +| CSV / TXT | ✔ | ✔ | * | * | A1-Style strings | +| ODS / FODS / UOS | ✔ | ✔ | | * | OpenFormula strings | +| WK\* | ✔ | | | * | Lotus parsed tokens | +| WQ\* / WB\* / QPW | | | | * | Quattro Pro tokens | +| NUMBERS | | | | * | Numbers parsed tokens | + +Asterisks (*) mark features that are not supported by the file formats. There is +no way to mark a dynamic array formula in the XLS file format. diff --git a/docz/docs/07-csf/07-features/02-hyperlinks.md b/docz/docs/07-csf/07-features/02-hyperlinks.md index 83f9c07b..09d52319 100644 --- a/docz/docs/07-csf/07-features/02-hyperlinks.md +++ b/docz/docs/07-csf/07-features/02-hyperlinks.md @@ -24,34 +24,32 @@ For example, the following snippet creates a link from cell `A3` to ws["A1"].l = { Target: "https://sheetjs.com", Tooltip: "Find us @ SheetJS.com!" }; ``` -Note that Excel does not automatically style hyperlinks. They will be displayed -using default style. SheetJS Pro Basic +:::note + +Excel does not automatically style hyperlinks. They will be displayed using +the default cell style. SheetJS Pro Basic extends this export with support for hyperlink styling. -
Live Example (click to show) +::: + +
Live Example (click to hide) ```jsx live /* The live editor requires this function wrapper */ -function ExportSimpleLink(props) { +function ExportSimpleLink(props) { return ( ); -} + /* Export to file (start a download) */ + var wb = XLSX.utils.book_new(); + XLSX.utils.book_append_sheet(wb, ws, "Sheet1"); + XLSX.writeFile(wb, "SheetJSSimpleLink.xlsx"); +}}>Export XLSX! ); } ```
@@ -72,6 +70,40 @@ ws["A4"].l = { Target: "mailto:ignored@dev.null" }; ws["A5"].l = { Target: "mailto:ignored@dev.null?subject=Test Subject" }; ``` +
Live Example (click to show) + +**This demo creates a XLSX spreadsheet with a `mailto` email link. The email +address input in the form never leaves your machine.** + +```jsx live +/* The live editor requires this function wrapper */ +function ExportRemoteLink(props) { + const [email, setEmail] = React.useState("ignored@dev.null"); + const set_email = React.useCallback((evt) => setEmail(evt.target.value)); + + /* Callback invoked when the button is clicked */ + const xport = React.useCallback(() => { + /* Create worksheet */ + var ws = XLSX.utils.aoa_to_sheet([ [ "HTTPS", "mailto" ] ]); + /* Add links */ + ws["A1"].l = { Target: "https://sheetjs.com" }; + ws["B1"].l = { Target: `mailto:${email}` }; + + /* Export to file (start a download) */ + var wb = XLSX.utils.book_new(); + XLSX.utils.book_append_sheet(wb, ws, "Sheet1"); + XLSX.writeFile(wb, "SheetJSRemoteLink.xlsx"); + }); + + return (<> + Email: +
+ ); +} +``` + +
+ ## Local Links Links to absolute paths should use the `file://` URI scheme: @@ -103,13 +135,55 @@ Links where the target is a cell or range or defined name in the same workbook ```js ws["C1"].l = { Target: "#E2" }; /* Link to cell E2 */ ws["C2"].l = { Target: "#Sheet2!E2" }; /* Link to cell E2 in sheet Sheet2 */ -ws["C3"].l = { Target: "#SomeDefinedName" }; /* Link to Defined Name */ +ws["C3"].l = { Target: "#SheetJSDName" }; /* Link to Defined Name */ ``` +
Live Example (click to show) + +```jsx live +/* The live editor requires this function wrapper */ +function ExportInternalLink(props) { return ( ); } +``` + +
+ +:::caution + +Some third-party tools like Google Sheets do not correctly parse hyperlinks in +XLSX documents. A workaround was added in library version 0.18.12. + +::: + ## HTML The HTML DOM parser will process `` links in the table: +
Live Example (click to hide) + ```jsx live /* The live editor requires this function wrapper */ function ExportHyperlink(props) { @@ -134,3 +208,5 @@ function ExportHyperlink(props) { ); } ``` + +
diff --git a/docz/docs/07-csf/07-features/index.md b/docz/docs/07-csf/07-features/index.md index b6919daa..94fffd29 100644 --- a/docz/docs/07-csf/07-features/index.md +++ b/docz/docs/07-csf/07-features/index.md @@ -11,12 +11,11 @@ are expected to serialize SheetJS workbooks in the underlying file format. The following topics are covered in sub-pages: ## Row and Column Properties @@ -340,9 +339,9 @@ var vbablob = wb.vbaraw; #### Code Names -By default, Excel will use `ThisWorkbook` or a translation `DieseArbeitsmappe` -for the workbook. Each worksheet will be identified using the default `Sheet#` -naming pattern even if the worksheet names have changed. +Excel will use `ThisWorkbook` (or a translation like `DieseArbeitsmappe`) as the +default Code Name for the workbook. Each worksheet will be identified using the +default `Sheet#` naming pattern even if the worksheet names have changed. A custom workbook code name will be stored in `wb.Workbook.WBProps.CodeName`. For exports, assigning the property will override the default value. @@ -374,4 +373,3 @@ function wb_has_macro(wb/*:workbook*/)/*:boolean*/ { return sheets.some((ws) => !!ws && ws['!type']=='macro'); } ``` - diff --git a/docz/docs/09-miscellany/02-errors.md b/docz/docs/09-miscellany/02-errors.md index fbda36a1..233af9d7 100644 --- a/docz/docs/09-miscellany/02-errors.md +++ b/docz/docs/09-miscellany/02-errors.md @@ -5,8 +5,8 @@ hide_table_of_contents: true --- Here are some common errors and their resolutions. This is not comprehensive. -The [issue tracker](https://github.com/SheetJS/sheetjs/issues) has a wealth of -information and user-contributed examples. +The [issue tracker](https://git.sheetjs.com/SheetJS/sheetjs/issues) has a +wealth of information and user-contributed examples. If issues are not covered in the docs or the issue tracker, or if a solution is not discussed in the documentation, we would appreciate a bug report. diff --git a/docz/docs/09-miscellany/03-source.md b/docz/docs/09-miscellany/03-source.md new file mode 100644 index 00000000..5560dcdb --- /dev/null +++ b/docz/docs/09-miscellany/03-source.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 3 +title: Source Code +hide_table_of_contents: true +--- + +The official source code repository is + +Mirrors: + +- [GitHub](https://github.com/sheetjs/sheetjs) +- [GitLab](https://gitlab.com/sheetjs/sheetjs) diff --git a/docz/docs/09-miscellany/07-license.md b/docz/docs/09-miscellany/07-license.md index 58c769c3..b07843cf 100644 --- a/docz/docs/09-miscellany/07-license.md +++ b/docz/docs/09-miscellany/07-license.md @@ -8,7 +8,30 @@ hide_table_of_contents: true SheetJS Community Edition is licensed under the "Apache 2.0 License". All rights not explicitly granted by the Apache 2.0 License are reserved by SheetJS LLC. -
License (click to show) +#### Required Attribution + +When integrating SheetJS CE in a project or service, the following text must be +added to open source disclosures: + +``` +SheetJS Community Edition -- https://sheetjs.com/ + +Copyright (C) 2012-present SheetJS LLC + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +``` + +
Complete License Text (click to show) ``` Apache License diff --git a/docz/docusaurus.config.js b/docz/docusaurus.config.js index 2b756be2..97d03a6f 100644 --- a/docz/docusaurus.config.js +++ b/docz/docusaurus.config.js @@ -80,7 +80,7 @@ const config = { position: 'right', }, { - href: 'https://github.com/sheetjs/sheetjs', + href: 'https://docs.sheetjs.com/docs/miscellany/source/', label: 'Source', position: 'right', }, @@ -132,7 +132,7 @@ const config = { }, { label: 'Source', - href: 'https://github.com/sheetjs/sheetjs', + href: 'https://docs.sheetjs.com/docs/miscellany/source/', }, ], },