contributing

This commit is contained in:
SheetJS 2023-08-29 23:44:38 -04:00
parent 57312901e1
commit 3f137265cc
20 changed files with 77 additions and 38 deletions

@ -196,7 +196,7 @@ These demos have been tested with Dojo Toolkit `1.10.4` and `1.17.3`.
The official Google CDN is out of date. This is a known CDN bug.
The script <https://docs.sheetjs.com/dojo/dojo.js> was fetched from the official
`1.17.3` uncompresssed release artifact[^2] on 2023-08-16.
`1.17.3` uncompressed release artifact[^2] on 2023-08-16.
:::

@ -293,9 +293,11 @@ function SheetJSFetchUL() {
### jQuery
`jQuery.ajax` (`$.ajax`) does not support binary data out of the box. A custom
`ajaxTransport` can add required functionality. SheetJS users have reported
success with `jquery.binarytransport.js` in IE10.
[jQuery](https://jquery.com/) is a JavaScript library that includes helpers for
performing "Ajax" network requests. `jQuery.ajax` (`$.ajax`) does not support
binary data out of the box[^1]. A custom `ajaxTransport` can add support.
SheetJS users have reported success with `jquery.binarytransport.js`[^2] in IE10.
After including the main `jquery.js` and `jquery.binarytransport.js` scripts,
`$.ajax` will support `dataType: "binary"` and `processData: false`.
@ -344,8 +346,8 @@ are still relevant.
#### axios
The `axios` library presents a Promise interface. Setting `responseType` to
`arraybuffer` ensures the return type is an ArrayBuffer:
[`axios`](https://axios-http.com/) presents a Promise based interface. Setting
`responseType` to `arraybuffer` ensures the return type is an ArrayBuffer:
```js
async function workbook_dl_axios(url) {
@ -446,17 +448,22 @@ function SheetJSAxiosUL() {
#### superagent
The `superagent` library usage mirrors XHR:
[`superagent`](https://github.com/visionmedia/superagent) is a network request
library with a "Fluent Interface"[^3]. Calling the `responseType` method with
`"arraybuffer"` will ensure the final response object is an `ArrayBuffer`:
```js
/* set up an async GET request with superagent */
superagent.get(url).responseType('arraybuffer').end(function(err, res) {
/* parse the data when it is received */
var data = new Uint8Array(res.body);
var workbook = XLSX.read(data, {type:"array"});
superagent
.get(url)
.responseType('arraybuffer')
.end(function(err, res) {
/* parse the data when it is received */
var data = new Uint8Array(res.body);
var workbook = XLSX.read(data, {type:"array"});
/* DO SOMETHING WITH workbook HERE */
});
/* DO SOMETHING WITH workbook HERE */
});
```
<details><summary><b>Live Download demo</b> (click to show)</summary>
@ -582,7 +589,7 @@ https.get('https://sheetjs.com/pres.numbers', function(res) {
:::note
This demo was last tested on 2023 May 21 against NodeJS `18.16.0`
This demo was last tested on 2023 August 29 against NodeJS `20.5.1`
:::
@ -616,7 +623,7 @@ async function parse_from_url(url) {
:::note
This demo was last tested on 2023 May 21 against NodeJS `18.16.0`
This demo was last tested on 2023 August 29 against NodeJS `20.5.1`
:::
@ -675,7 +682,7 @@ var url = 'https://sheetjs.com/pres.numbers';
request(url, {encoding: null}, function(err, res, data) {
if(err || res.statusCode !== 200) return;
/* if the request was succesful, parse the data */
/* if the request was successful, parse the data */
// highlight-next-line
var wb = XLSX.read(data);
@ -689,7 +696,7 @@ request(url, {encoding: null}, function(err, res, data) {
:::note
This demo was last tested on 2023 May 21 against request `2.88.2`
This demo was last tested on 2023 August 29 against request `2.88.2`
:::
@ -725,14 +732,14 @@ async function workbook_dl_axios(url) {
:::note
This demo was last tested on 2023 May 21 against Axios `1.4.0`
This demo was last tested on 2023 August 29 against Axios `1.5.0`
:::
1) Install the [NodeJS module](/docs/getting-started/installation/nodejs)
<CodeBlock language="bash">{`\
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz axios@1.4.0`}
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz axios@1.5.0`}
</CodeBlock>
2) Save the following to `SheetJSAxios.js`:
@ -765,3 +772,7 @@ Other demos show network operations in special platforms:
- [React Native "Fetching Remote Data"](/docs/demos/mobile/reactnative#fetching-remote-data)
- [NativeScript "Fetching Remote Files"](/docs/demos/mobile/nativescript#fetching-remote-files)
[^1]: See [`dataType` in `jQuery.ajax`](https://api.jquery.com/jQuery.ajax/#:~:text=the%20%27dataType%27%20parameter.-,dataType,-(default%3A%20Intelligent) in the official jQuery documentation.
[^2]: See [the official `jquery.binarytransport.js` repo](https://github.com/henrya/js-jquery/tree/master/BinaryTransport) for more details.
[^3]: See ["Fluent interface"](https://en.wikipedia.org/wiki/Fluent_interface) on Wikipedia.

@ -340,7 +340,7 @@ manually open the `SheetJSNS` app.
The app can be tested with the following sequence in the simulator:
- Tap "Export File". A dialog will print where the file was written. Typicaly
- Tap "Export File". A dialog will print where the file was written. Typically
the URL is `/data/user/0/org.nativescript.SheetJSNS/files/SheetJSNS.xls`
- Pull the file from the simulator:

@ -18,7 +18,7 @@ For other APIs, user code can pass data to `XLSX.read` or use data generated by
This demo looks at various web APIs. More specific approaches for deployments
like mobile apps are covered in their respective demos.
:::note
:::note pass
Some snippets are also available in the "Common Use Cases" section:
@ -27,7 +27,9 @@ Some snippets are also available in the "Common Use Cases" section:
:::
:::warning
## Web Browsers
:::warning pass
Not all web APIs are supported in all browsers. For example, Firefox does not
support the "File System Access API".
@ -37,7 +39,7 @@ client browser. Some APIs do not give any feedback.
:::
## Binary Data
### Binary Data
Modern browser APIs typically use typed arrays or `Blob` or `File` structures.
@ -120,7 +122,7 @@ const u8 = XLSX.write(workbook, { type: "buffer", bookType: "xlsx" });
const blob = new Blob([u8], { type: "application/vnd.ms-excel" });
```
## HTML5 Download Attribute
### HTML5 Download Attribute
_Writing Files_
@ -173,7 +175,7 @@ includes a live demo.
:::
## File API
### File API
_Reading Files_
@ -193,7 +195,7 @@ async function handleFileAsync(e) {
input_dom_element.addEventListener("change", handleFileAsync, false);
```
## HTML Drag and Drop API
### HTML Drag and Drop API
_Reading Files_
@ -221,7 +223,7 @@ drop_dom_element.addEventListener("dragover", suppress, false);
drop_dom_element.addEventListener("dragenter", suppress, false);
```
## File System Access API
### File System Access API
:::caution Limited Browser Support
@ -235,7 +237,8 @@ the feature in version 86. Safari did not support File System Access API.
This live example reads a file then tries to save as XLSX.
```jsx live
function SheetJSRoundTripFileSystemAPI() { return ( <button onClick={async () => {
function SheetJSRoundTripFileSystemAPI() { return window.showSaveFilePicker ? (
<button onClick={async () => {
/* Show picker and get data */
const [rFile] = await window.showOpenFilePicker({
types: [{
@ -264,7 +267,8 @@ function SheetJSRoundTripFileSystemAPI() { return ( <button onClick={async () =>
/* close stream to commit file */
wstream.close();
}}>Click to read then save as XLSX</button> ) }
}}>Click to read then save as XLSX</button>
) : ( <b>This browser does not support File System Access API</b> ); }
```
</details>
@ -323,7 +327,7 @@ wstream.write(XLSX.write(wb, { bookType: ext, type: "buffer" }))
wstream.close();
```
## File and Directory Entries API
### File and Directory Entries API
:::caution Deprecated
@ -355,7 +359,7 @@ window.requestFileSystem(window.PERSISTENT, 0, (fs) => {
});
```
## Internet Explorer
### Internet Explorer
Internet Explorer offered proprietary APIs that were not adopted by Chromium.

@ -265,6 +265,7 @@ This demo was tested in the following deployments:
| `darwin-x64` | `2788d71` | 2023-07-24 |
| `darwin-arm` | `2788d71` | 2023-06-05 |
| `linux-x64` | `2788d71` | 2023-06-02 |
| `linux-arm` | `2788d71` | 2023-08-29 |
| `win10-x64` | `2788d71` | 2023-07-24 |
When the demo was tested, commit `2788d71` corresponded to the latest release.

@ -40,7 +40,7 @@ These instructions were tested on the following platforms:
| Platform | Test Date |
|:------------------------------|:-----------|
| Linux (Steam Deck Holo 3.4.8) | 2023-07-12 |
| Linux (Ubuntu 18.04 AArch64) | 2023-04-13 |
| Linux (Debian 11 AArch64) | 2023-08-29 |
| MacOS 10.13 (x64) | 2023-04-04 |
| MacOS 13.0 (ARM64) | 2023-04-13 |
| Windows 10 (x64) + WSL Ubuntu | 2023-07-23 |
@ -277,16 +277,17 @@ make init
This step may take a while as it will be downloading a number of test files.
3) Run a short test, then run a build
3) Run a build and verify with a short test:
```bash
# Short test
make test_misc
# Full Build
cd modules; make clean; make; cd ..
make
make dist
# Short test
make test_misc
# Reset repo
git checkout -- .
```
@ -374,8 +375,30 @@ The `xlsx.js` and `xlsx.mjs` files are constructed from the files in the `bits`
subfolder. The build script (run `make`) will concatenate the individual bits
to produce the scripts.
To produce the dist files, run `make dist`. The dist files are updated in each
version release and *should not be committed between versions*.
When changing the `.js` scripts in `bits`, the following sequence rebuilds the
`xlsx.js` and `xlsx.mjs` scripts:
```bash
make
```
When changing the `.ts` scripts in `modules`, the following sequence rebuilds
the `xlsx.js` and `xlsx.mjs` scripts:
```bash
cd modules; make clean; make; cd ..
```
To produce the dist files, run `make dist`.
:::info pass
The various `xlsx.*` scripts in the base folder and the files in the `dist`
folder are updated on each version release.
**They should not be committed between versions!**
:::
## Tests