From 727a67b15215eaa925b512d1c8b61343ebf9c073 Mon Sep 17 00:00:00 2001 From: SheetJS Date: Sat, 27 May 2023 19:07:45 -0400 Subject: [PATCH] html-out --- .../01-installation/index.md | 29 ++++ docz/docs/02-getting-started/02-example.mdx | 2 +- docz/docs/02-getting-started/index.md | 11 +- docz/docs/03-demos/07-data/09-alasql.md | 4 +- docz/docs/06-solutions/05-output.md | 8 +- .../07-utilities/{07-html.md => 05-html.md} | 54 +++++++- docz/docs/08-api/07-utilities/07-csv.md | 125 ++++++++++++++++++ docz/docs/08-api/07-utilities/09-formulae.md | 2 + docz/docs/08-api/07-utilities/index.md | 95 +------------ docz/docs/08-api/index.md | 41 ++++-- docz/docs/09-miscellany/02-errors.md | 4 +- docz/package.json | 14 +- 12 files changed, 261 insertions(+), 128 deletions(-) create mode 100644 docz/docs/02-getting-started/01-installation/index.md rename docz/docs/08-api/07-utilities/{07-html.md => 05-html.md} (86%) create mode 100644 docz/docs/08-api/07-utilities/07-csv.md diff --git a/docz/docs/02-getting-started/01-installation/index.md b/docz/docs/02-getting-started/01-installation/index.md new file mode 100644 index 0000000..ca685dd --- /dev/null +++ b/docz/docs/02-getting-started/01-installation/index.md @@ -0,0 +1,29 @@ +--- +pagination_prev: getting-started/index +pagination_next: getting-started/example +hide_table_of_contents: true +title: Installation +------ + +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + + is the primary software distribution site. Please +read the installation instructions for your use case: + + + +:::info + +[Watch the repo](https://git.sheetjs.com/SheetJS/sheetjs) or subscribe to the +[RSS feed](https://git.sheetjs.com/sheetjs/sheetjs/tags.rss) to be notified when +new versions are released! + +::: diff --git a/docz/docs/02-getting-started/02-example.mdx b/docz/docs/02-getting-started/02-example.mdx index 8b69063..6001e57 100644 --- a/docz/docs/02-getting-started/02-example.mdx +++ b/docz/docs/02-getting-started/02-example.mdx @@ -1,5 +1,5 @@ --- -pagination_prev: getting-started/index +pagination_prev: getting-started/installation/index sidebar_position: 2 --- diff --git a/docz/docs/02-getting-started/index.md b/docz/docs/02-getting-started/index.md index e80960f..014826e 100644 --- a/docz/docs/02-getting-started/index.md +++ b/docz/docs/02-getting-started/index.md @@ -1,17 +1,20 @@ --- hide_table_of_contents: true -pagination_next: getting-started/example +pagination_next: getting-started/installation/index --- +import DocCardList from '@theme/DocCardList'; +import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; + # Getting Started ["Tutorial"](/docs/getting-started/example) is a live example that covers general data munging and data export to spreadsheets. -## Installation +["Demos"](/docs/demos) include discussions and tested examples for common +deployments and use cases. -import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; +## Installation is the primary software distribution site. Please read the installation instructions for your use case: diff --git a/docz/docs/03-demos/07-data/09-alasql.md b/docz/docs/03-demos/07-data/09-alasql.md index e696fa0..a96f292 100644 --- a/docz/docs/03-demos/07-data/09-alasql.md +++ b/docz/docs/03-demos/07-data/09-alasql.md @@ -181,14 +181,12 @@ By default the workbook is parsed and `sheet_to_json` is used to pull data: The `XLSX` "into" target calls `XLSX.writeFile` under the hood: ```js -const { promise: alasql } = require("alasql"); - (async() => { const data = [ { Name: "Bill Clinton", Index: 42 }, { Name: "Someone Else", Index: 47 } ]; - await alasql(`SELECT * INTO XLSX("PresMod5.xlsx") FROM ?`, [data]); + await alasql.promise(`SELECT * INTO XLSX("PresMod5.xlsx") FROM ?`, [data]); /* PresMod5.xlsx will be created */ })(); ``` diff --git a/docz/docs/06-solutions/05-output.md b/docz/docs/06-solutions/05-output.md index 387b2a5..373e185 100644 --- a/docz/docs/06-solutions/05-output.md +++ b/docz/docs/06-solutions/05-output.md @@ -805,8 +805,8 @@ var csv = XLSX.utils.sheet_to_csv(worksheet, opts); ``` This snapshot is designed to replicate the "CSV UTF-8 (`.csv`)" output type. -["Delimiter-Separated Output"](/docs/api/utilities#delimiter-separated-output) describes the -function and the optional `opts` argument in more detail. +["CSV and Text"](/docs/api/utilities/csv) describes the function and the +optional `opts` argument in more detail. _Generate "Text" from a single worksheet_ @@ -815,8 +815,8 @@ var txt = XLSX.utils.sheet_to_txt(worksheet, opts); ``` This snapshot is designed to replicate the "UTF-16 Text (`.txt`)" output type. -["Delimiter-Separated Output"](/docs/api/utilities#delimiter-separated-output) describes the -function and the optional `opts` argument in more detail. +["CSV and Text"](/docs/api/utilities/csv) describes the function and the +optional `opts` argument in more detail. _Generate a list of formulae from a single worksheet_ diff --git a/docz/docs/08-api/07-utilities/07-html.md b/docz/docs/08-api/07-utilities/05-html.md similarity index 86% rename from docz/docs/08-api/07-utilities/07-html.md rename to docz/docs/08-api/07-utilities/05-html.md index 4f0b08e..44ac7fd 100644 --- a/docz/docs/08-api/07-utilities/07-html.md +++ b/docz/docs/08-api/07-utilities/05-html.md @@ -1,5 +1,5 @@ --- -sidebar_position: 7 +sidebar_position: 5 title: HTML --- @@ -17,6 +17,58 @@ HTML format and HTML table utilities. ::: +## HTML Table Output + +```js +var html = XLSX.utils.sheet_to_html(ws, opts); +``` + +As an alternative to the `writeFile` HTML type, `XLSX.utils.sheet_to_html` also +produces HTML output. The function takes an options argument: + +| Option Name | Default | Description | +|:------------|:--------:|:----------------------------------------------------| +| `id` | | Specify the `id` attribute for the `TABLE` element | +| `editable` | false | If true, set `contenteditable="true"` for every TD | +| `header` | | Override header | +| `footer` | | Override footer | + +Starting from [the sample file `pres.numbers`](https://sheetjs.com/pres.numbers): + +```jsx live +function SheetJSHTML() { + const url = "https://sheetjs.com/pres.numbers"; + const [__html, setHTML] = React.useState(""); + React.useEffect(() => { (async() => { + /* download file and parse */ + const wb = XLSX.read(await (await fetch(url)).arrayBuffer()); + /* get the first worksheet */ + const ws = wb.Sheets[wb.SheetNames[0]]; + + /* generate HTML */ + const html = XLSX.utils.sheet_to_html(ws); + + setHTML(html); + })(); }, []); + return ( <> + XLSX.utils.sheet_to_html(ws) +
+ ); +} +``` + +### Implementation Details + +The generated table will include special data attributes on each `TD` element: + +| Attribute | Description | +|:----------|:-------------------------------------------------------------| +| `data-t` | Override [Cell Type](/docs/csf/cell#data-types) | +| `data-v` | Override Cell Value | +| `data-z` | Override [Number Format](/docs/csf/features/nf) | + +External cell links will be written as `A` tags wrapping the cell contents. + ## HTML Table Input ### Create New Sheet diff --git a/docz/docs/08-api/07-utilities/07-csv.md b/docz/docs/08-api/07-utilities/07-csv.md new file mode 100644 index 0000000..a6f2198 --- /dev/null +++ b/docz/docs/08-api/07-utilities/07-csv.md @@ -0,0 +1,125 @@ +--- +sidebar_position: 7 +title: CSV and Text +--- + +CSV is a common format for data interchange. Spreadsheet applications such as +Excel also support other delimiter-separated formats including "Text" (using a +tab character as the field separator). + +The general write functions (`XLSX.write` and `XLSX.writeFile`) support `csv` +and `txt` (for CSV and tab-separated values respectively), but the specific +utility functions generate raw JS strings for further processing. + +## Live Demo + +After choosing a file, the demo will print the data from each worksheet: + +```jsx live +function SheetJSPreCSView() { + const [__html, setHTML] = React.useState("Select a file"); + + const process = (ab) => { + const wb = XLSX.read(ab); + var res = ""; + wb.SheetNames.forEach((n, idx) => { + const ws = wb.Sheets[n]; + res += `Sheet #${idx+1} (${n})\n`; + res += XLSX.utils.sheet_to_csv(ws) + "\n\n"; + }); + setHTML(res); + }; + React.useEffect(() => { (async() => { + const url = "https://sheetjs.com/pres.numbers"; + process(await (await fetch(url)).arrayBuffer()); + })(); }, []); + + return ( <> + { + process(await e.target.files[0].arrayBuffer()); + }}/> + 
+   );
+}
+```
+
+## Delimiter-Separated Output
+
+**Export worksheet data in CSV, TSV, or other delimiter-separated format**
+
+```js
+var csv = XLSX.utils.sheet_to_csv(ws, opts);
+```
+
+As an alternative to the `writeFile` CSV type, `XLSX.utils.sheet_to_csv` also
+produces CSV output.  The function takes an options argument:
+
+| Option Name  |  Default | Description                                        |
+| :----------- | :------: | :------------------------------------------------- |
+|`FS`          |  `","`   | "Field Separator"  delimiter between fields        |
+|`RS`          |  `"\n"`  | "Record Separator" delimiter between rows          |
+|`dateNF`      |  FMT 14  | Use specified date format in string output         |
+|`strip`       |  false   | Remove trailing field separators in each record ** |
+|`blankrows`   |  true    | Include blank lines in the CSV output              |
+|`skipHidden`  |  false   | Skips hidden rows/columns in the CSV output        |
+|`forceQuotes` |  false   | Force quotes around fields                         |
+
+- `strip` will remove trailing commas from each line under default `FS/RS`
+- `blankrows` must be set to `false` to skip blank lines.
+- Fields containing the record or field separator will automatically be wrapped
+  in double quotes; `forceQuotes` forces all cells to be wrapped in quotes.
+
+
+The following example shows `FS` and `RS` options:
+
+```jsx live
+function SheetJSCSVTest() {
+  var ws = XLSX.utils.aoa_to_sheet([
+    ["S", "h", "e", "e", "t", "J", "S"],
+    [  1,   2,    ,    ,   5,   6,   7],
+    [  2,   3,    ,    ,   6,   7,   8],
+    [  3,   4,    ,    ,   7,   8,   9],
+    [  4,   5,   6,   7,   8,   9,   0]
+  ]);
+  return ( 
+    Worksheet (as HTML)
+    

+    XLSX.utils.sheet_to_csv(ws)

+    {XLSX.utils.sheet_to_csv(ws)}


+    XLSX.utils.sheet_to_csv(ws, {'{'} FS: "\t" {'}'})

+    {XLSX.utils.sheet_to_csv(ws, { FS: "\t" })}


+    XLSX.utils.sheet_to_csv(ws, {'{'} FS: ":", RS: "|" {'}'})

+    {XLSX.utils.sheet_to_csv(ws, { FS: ":", RS: "|" })}

+  
 );
+}
+```
+
+### CSV Output
+
+**Export worksheet data in "Comma-Separated Values" (CSV)**
+
+```js
+var csv = XLSX.utils.sheet_to_csv(ws, opts);
+```
+
+`sheet_to_csv` uses the comma character as the field separator by default. This
+utility function mirrors the `csv` book type in `XLSX.write` or `XLSX.writeFile`.
+
+`sheet_to_csv` always returns a JS string and always omits byte-order marks.
+
+### UTF-16 Text Output
+
+**Export worksheet data in "UTF-16 Text" or Tab-Separated Values (TSV)**
+
+```js
+var txt = XLSX.utils.sheet_to_txt(ws, opts);
+```
+
+`sheet_to_txt` uses the tab character as the field separator. This utility
+function matches the `txt` book type in `XLSX.write` or `XLSX.writeFile`.
+
+If encoding support is available, the output will be encoded in `CP1200` and the
+UTF-16 BOM will be added. If encoding support is not available, the output will
+be encoded as a standard `string`.
+
+`XLSX.utils.sheet_to_txt` takes the same arguments as `sheet_to_csv`.
diff --git a/docz/docs/08-api/07-utilities/09-formulae.md b/docz/docs/08-api/07-utilities/09-formulae.md
index 71e6183..99d0a9a 100644
--- a/docz/docs/08-api/07-utilities/09-formulae.md
+++ b/docz/docs/08-api/07-utilities/09-formulae.md
@@ -4,6 +4,8 @@ title: Array of Formulae
 pagination_next: miscellany/formats
 ---
 
+**Extract all formulae from a worksheet**
+
 ```js
 var fmla_arr = XLSX.utils.sheet_to_formulae(ws);
 ```
diff --git a/docz/docs/08-api/07-utilities/index.md b/docz/docs/08-api/07-utilities/index.md
index 5d4008d..ca517bc 100644
--- a/docz/docs/08-api/07-utilities/index.md
+++ b/docz/docs/08-api/07-utilities/index.md
@@ -284,102 +284,11 @@ function SheetJSHeaderOrder() {
 
 ## Delimiter-Separated Output
 
-```js
-var csv = XLSX.utils.sheet_to_csv(ws, opts);
-```
-
-As an alternative to the `writeFile` CSV type, `XLSX.utils.sheet_to_csv` also
-produces CSV output.  The function takes an options argument:
-
-| Option Name  |  Default | Description                                        |
-| :----------- | :------: | :------------------------------------------------- |
-|`FS`          |  `","`   | "Field Separator"  delimiter between fields        |
-|`RS`          |  `"\n"`  | "Record Separator" delimiter between rows          |
-|`dateNF`      |  FMT 14  | Use specified date format in string output         |
-|`strip`       |  false   | Remove trailing field separators in each record ** |
-|`blankrows`   |  true    | Include blank lines in the CSV output              |
-|`skipHidden`  |  false   | Skips hidden rows/columns in the CSV output        |
-|`forceQuotes` |  false   | Force quotes around fields                         |
-
-- `strip` will remove trailing commas from each line under default `FS/RS`
-- `blankrows` must be set to `false` to skip blank lines.
-- Fields containing the record or field separator will automatically be wrapped
-  in double quotes; `forceQuotes` forces all cells to be wrapped in quotes.
-- `XLSX.write` with `csv` type will always prepend the UTF-8 byte-order mark for
-  Excel compatibility.  `sheet_to_csv` returns a JS string and omits the mark.
-  Using `XLSX.write` with type `string` will also skip the mark.
-
-
-Starting from the example worksheet:
-
-```jsx live
-function SheetJSCSVTest() {
-  var ws = XLSX.utils.aoa_to_sheet([
-    ["S", "h", "e", "e", "t", "J", "S"],
-    [  1,   2,    ,    ,   5,   6,   7],
-    [  2,   3,    ,    ,   6,   7,   8],
-    [  3,   4,    ,    ,   7,   8,   9],
-    [  4,   5,   6,   7,   8,   9,   0]
-  ]);
-  return ( 
-    Worksheet (as HTML)
-    

-    XLSX.utils.sheet_to_csv(ws)

-    {XLSX.utils.sheet_to_csv(ws)}


-    XLSX.utils.sheet_to_csv(ws, {'{'} FS: "\t" {'}'})

-    {XLSX.utils.sheet_to_csv(ws, { FS: "\t" })}


-    XLSX.utils.sheet_to_csv(ws, {'{'} FS: ":", RS: "|" {'}'})

-    {XLSX.utils.sheet_to_csv(ws, { FS: ":", RS: "|" })}

-  
 );
-}
-```
-
-**UTF-16 Text Output**
-
-```js
-var txt = XLSX.utils.sheet_to_txt(ws, opts);
-```
-
-The `txt` output type uses the tab character as the field separator.  If the
-`codepage` library is available (included in full distribution but not core),
-the output will be encoded in `CP1200` and the UTF-16 BOM will be added.
-
-`XLSX.utils.sheet_to_txt` takes the same arguments as `sheet_to_csv`.
-
+[**This has been moved to a separate page**](/docs/api/utilities/csv)
 
 ## HTML Output
 
-```js
-var html = XLSX.utils.sheet_to_html(ws, opts);
-```
-
-As an alternative to the `writeFile` HTML type, `XLSX.utils.sheet_to_html` also
-produces HTML output.  The function takes an options argument:
-
-| Option Name |  Default | Description                                         |
-| :---------- | :------: | :-------------------------------------------------- |
-|`id`         |          | Specify the `id` attribute for the `TABLE` element  |
-|`editable`   |  false   | If true, set `contenteditable="true"` for every TD  |
-|`header`     |          | Override header (default `html body`)               |
-|`footer`     |          | Override footer (default `/body /html`)             |
-
-Starting from the example worksheet:
-
-```jsx live
-function SheetJSHTML() {
-  var ws = XLSX.utils.aoa_to_sheet([
-    ["S", "h", "e", "e", "t", "J", "S"],
-    [  1,   2,    ,    ,   5,   6,   7],
-    [  2,   3,    ,    ,   6,   7,   8],
-    [  3,   4,    ,    ,   7,   8,   9],
-    [  4,   5,   6,   7,   8,   9,   0]
-  ]);
-  return ( 
-    XLSX.utils.sheet_to_html(ws)
-    

-  
 );
-}
-```
+[**This has been moved to a separate page**](/docs/api/utilities/html#html-table-output)
 
 ## Array Output
 
diff --git a/docz/docs/08-api/index.md b/docz/docs/08-api/index.md
index b8c8ca6..6ff55ea 100644
--- a/docz/docs/08-api/index.md
+++ b/docz/docs/08-api/index.md
@@ -42,46 +42,61 @@ Write options are described in the [Writing Options](/docs/api/write-options) se
 
 Utilities are available in the `XLSX.utils` object.
 
-The following are described in [`A1` Utilities](/docs/csf/general#utilities)
+The methods are covered in dedicated pages:
 
-**Cell and cell address manipulation:**
+**[`A1` Utilities](/docs/csf/general#utilities)**
+
+_Cell and cell address manipulation:_
 
 - `encode_row / decode_row` converts between 0-indexed rows and 1-indexed rows.
 - `encode_col / decode_col` converts between 0-indexed columns and column names.
 - `encode_cell / decode_cell` converts cell addresses.
 - `encode_range / decode_range` converts cell ranges.
 
-The following are described in ["HTML" section of "Utility Functions"](/docs/api/utilities/html):
+**["HTML" section of "Utility Functions"](/docs/api/utilities/html)**
 
-**Reading from HTML:**
+_Reading from HTML:_
 
 - `table_to_sheet` converts a DOM TABLE element to a worksheet.
 - `table_to_book` converts a DOM TABLE element to a worksheet.
 - `sheet_add_dom` adds data from a DOM TABLE element to an existing worksheet.
 
-The following are described in the [Utility Functions](/docs/api/utilities):
+_Writing HTML:_
 
-**Constructing:**
+- `sheet_to_html` generates HTML output.
+
+**["CSV and Text" section of "Utility Functions"](/docs/api/utilities/csv)**
+
+_Writing CSV and Text:_
+
+- `sheet_to_csv` generates delimiter-separated-values output.
+- `sheet_to_txt` generates UTF-16 formatted text.
+
+**["Array of Formulae" section of "Utility Functions"](/docs/api/utilities/formulae)**
+
+_Exporting Formulae:_
+
+- `sheet_to_formulae` generates a list of formulae or cell value assignments.
+
+**[Utility Functions](/docs/api/utilities)**
+
+_Workbook Operations:_
 
 - `book_new` creates an empty workbook
 - `book_append_sheet` adds a worksheet to a workbook
 
-**Importing:**
+_Importing Data:_
 
 - `aoa_to_sheet` converts an array of arrays of JS data to a worksheet.
 - `json_to_sheet` converts an array of JS objects to a worksheet.
 - `sheet_add_aoa` adds an array of arrays of JS data to an existing worksheet.
 - `sheet_add_json` adds an array of JS objects to an existing worksheet.
 
-**Exporting:**
+_Exporting Data:_
 
 - `sheet_to_json` converts a worksheet object to an array of JSON objects.
-- `sheet_to_csv` generates delimiter-separated-values output.
-- `sheet_to_txt` generates UTF-16 formatted text.
-- `sheet_to_html` generates HTML output.
-- `sheet_to_formulae` generates a list of formulae or cell value assignments.
 
-**Miscellaneous**
+_Miscellaneous_
 
 - `format_cell` generates the text value for a cell (using number formats).
 - `sheet_set_array_formula` adds an array formula to a worksheet
diff --git a/docz/docs/09-miscellany/02-errors.md b/docz/docs/09-miscellany/02-errors.md
index 948db7d..f2f9a83 100644
--- a/docz/docs/09-miscellany/02-errors.md
+++ b/docz/docs/09-miscellany/02-errors.md
@@ -13,7 +13,7 @@ wealth of information and user-contributed examples.
 
 **Many of these errors have been fixed in newer releases!**  Ensure that the
 latest version of the library is being used. Some legacy endpoints are out of
-date.  [Review the Installation instructions.](/docs/getting-started#installation)
+date.  [Review the Installation instructions.](/docs/getting-started/installation)
 
 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.
@@ -41,7 +41,7 @@ Uncaught TypeError: Cannot read property 'utils' of undefined
 The root cause is an undefined `XLSX` variable.  This usually means the library
 was not properly loaded.
 
-[Review the Installation instructions.](/docs/getting-started#installation)
+[Review the Installation instructions.](/docs/getting-started/installation)
 
 If the error shows up while using the latest version, projects may require
 other configuration or loading strategies.
diff --git a/docz/package.json b/docz/package.json
index 36f4148..f339b2d 100644
--- a/docz/package.json
+++ b/docz/package.json
@@ -15,12 +15,12 @@
   },
   "dependencies": {
     "@cmfcmf/docusaurus-search-local": "0.11.0",
-    "@docusaurus/core": "2.3.1",
-    "@docusaurus/plugin-client-redirects": "2.3.1",
-    "@docusaurus/preset-classic": "2.3.1",
-    "@docusaurus/theme-common": "2.3.1",
-    "@docusaurus/theme-live-codeblock": "2.3.1",
-    "@docusaurus/theme-mermaid": "2.3.1",
+    "@docusaurus/core": "2.4.1",
+    "@docusaurus/plugin-client-redirects": "2.4.1",
+    "@docusaurus/preset-classic": "2.4.1",
+    "@docusaurus/theme-common": "2.4.1",
+    "@docusaurus/theme-live-codeblock": "2.4.1",
+    "@docusaurus/theme-mermaid": "2.4.1",
     "@mdx-js/react": "1.6.22",
     "clsx": "1.2.1",
     "prism-react-renderer": "1.3.5",
@@ -29,7 +29,7 @@
     "xlsx": "https://cdn.sheetjs.com/xlsx-0.19.3/xlsx-0.19.3.tgz"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.3.1"
+    "@docusaurus/module-type-aliases": "2.4.1"
   },
   "browserslist": {
     "production": [