This commit is contained in:
SheetJS 2023-01-13 22:13:35 -05:00
parent 972d4eed27
commit 89ddafaaeb
8 changed files with 188 additions and 73 deletions

@ -1,5 +1,7 @@
---
title: Adobe Apps
title: Photoshop and Creative Suite
pagination_prev: demos/server
pagination_next: demos/gsheet
---
import Tabs from '@theme/Tabs';
@ -185,4 +187,3 @@ extension HTML
UXP officially recommends `require` and NodeJS Modules for third party support.
[Use the "Frameworks" instructions to download.](/docs/getting-started/installation/frameworks)

@ -1,5 +1,7 @@
---
title: Chrome Extensions
title: Chrome and Chromium
pagination_prev: demos/server
pagination_next: demos/gsheet
---
:::warning

@ -1,5 +1,7 @@
---
title: Excel JavaScript API
pagination_prev: demos/server
pagination_next: demos/gsheet
---
:::info
@ -48,22 +50,7 @@ Run `yo office` from the command line. It will ask a few questions.
- "What do you want to name your add-in?": "SheetJSImport"
You will see a screen like
```
? Choose a project type: Excel Custom Functions Add-in project
? Choose a script type: JavaScript
? What do you want to name your add-in? SheetJSImport
----------------------------------------------------------------------------------
Creating SheetJSImport add-in for Excel using JavaScript and Excel-functions
at C:\Users\SheetJS\Documents\SheetJSImport
----------------------------------------------------------------------------------
```
It helpfully prints out the next steps:
The script will create a new project and helpfully print the next steps:
```powershell
cd SheetJSImport
@ -102,7 +89,8 @@ function version() {
}
```
The `manifest.xml` should also be updated to reflect the function namespace:
The `manifest.xml` should also be updated to reflect the function namespace.
Search for `Functions.NameSpace` in the file and replace the line with:
```xml
<bt:String id="Functions.Namespace" DefaultValue="SHEETJS"/>
@ -231,8 +219,8 @@ async function extern() {
/* get and return data */
var ws = wb.Sheets[wb.SheetNames[0]]; // get first worksheet
var aoa = XLSX.utils.sheet_to_json(ws, { header: 1 }); // get data as array of arrays
return [[url]];
} catch(e) { return [[e]]; } // pass error back to Excel
return aoa;
} catch(e) { return [[e.message || e]]; } // pass error back to Excel
}
```
@ -244,5 +232,9 @@ should pull in the data and generate a dynamic array:
![`SHEETJS.VERSION` output](pathname:///files/xlcfextern1.png)
:::note
[SheetJS Pro](https://sheetjs.com/pro) offers additional features that can be
used in Excel Custom Functions and Add-ins
:::

@ -0,0 +1,5 @@
{
"label": "App Extensions",
"position": 10,
"collapsed": false
}

@ -0,0 +1,24 @@
---
title: Extensions
pagination_prev: demos/server
pagination_next: demos/gsheet
---
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
Thanks to the broad availability of powerful engines, JavaScript is a popular
language for writing extensions for apps. Some applications like Chromium use V8
while others use engines that only support ES3 JavaScript. With conservative use
of modern language features, SheetJS can be used in many app extensions.
Demos for common apps are included in separate pages:
<ul>{useCurrentSidebarCategory().items.map((item, index) => {
const listyle = (item.customProps?.icon) ? {
listStyleImage: `url("${item.customProps.icon}")`
} : {};
return (<li style={listyle} {...(item.customProps?.class ? {className: item.customProps.class}: {})}>
<a href={item.href}>{item.label}</a>{item.customProps?.summary && (" - " + item.customProps.summary)}
</li>);
})}</ul>

@ -1,5 +1,6 @@
---
title: Google Sheets
pagination_prev: demos/extensions/index
---
import Tabs from '@theme/Tabs';

@ -28,7 +28,14 @@ Folders:
After cloning the repo, running `make help` will display a list of commands.
## OS-Specific Setup
## Setup
These instructions will cover system configuration, cloning the source repo,
building, reproducing official releases, and running NodeJS and browser tests.
### Install dependencies
#### OS-Specific Setup
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@ -36,9 +43,7 @@ import TabItem from '@theme/TabItem';
<Tabs>
<TabItem value="wsl" label="Windows WSL">
The MacOS/Linux workflow works in WSL. Initial setup is involved:
1) Install mercurial and subversion.
A) Install mercurial and subversion.
```bash
# Install support programs for the build and test commands
@ -48,21 +53,23 @@ sudo apt-get install mercurial subversion
sudo add-apt-repository --remove ppa:mercurial-ppa/releases
```
2) Install NodeJS
B) Install NodeJS
```bash
# Install bootstrap NodeJS and NPM within the WSL
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt-get install -y nodejs
```
# CLOSE AND REOPEN SHELL BEFORE CONTINUING
Exit the WSL window and open a new one before proceeding:
```bash
# Switch to `n`-managed NodeJS
sudo npm i -g n
sudo n 16
```
3) Build and install a version of Git with proper SSL support:
C) Build and install a version of Git with proper SSL support:
```bash
# Git does not support OpenSSL out of the box, must do this
@ -71,15 +78,47 @@ chmod +x compile-git-with-openssl.sh
./compile-git-with-openssl.sh
```
(instructions continued in the MacOS/Linux part)
D) Set `git` config `core.autocrlf` setting to `false`. The following commands
should be run twice, once within PowerShell and once within WSL bash:
```powershell
git config --global --add core.autocrlf false
git config --global --unset core.autocrlf true
```
</TabItem>
<TabItem value="osx" label="MacOS/Linux">
<TabItem value="osx" label="MacOS">
Initial setup:
A) Run `git`. If Xcode or the command-line tools are not installed, you will be
asked to install. Click "Install" and run through the steps.
0) Ensure mercurial, subversion, and NodeJS are installed. The WSL instructions
will have installed these dependencies, so WSL users can skip to step 1.
B) Open a terminal window and install Homebrew:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
C) Close the window, open a new terminal window, and disable analytics:
```bash
brew analytics off
```
To confirm analytics are disabled, run
```bash
brew analytics state
```
It should print `Analytics are disabled.`
D) Install Mercurial and Subversion:
```bash
brew install mercurial subversion
```
E) Install NodeJS
:::note
@ -88,20 +127,19 @@ for "LTS" and "Current" releases. The "LTS" version should be installed.
:::
Mercurial and Subversion:
<Tabs>
</TabItem>
<TabItem value="l" label="Linux">
On Linux, install using the system package manager. Debian and Ubuntu use `apt`:
A) Install `mercurial`, `git`, and `subversion` using the system package
manager. On Debian and Ubuntu systems, `apt-get` installs packages:
```bash
sudo apt-get install mercurial subversion
sudo apt-get install git mercurial subversion
```
Other Linux distributions may use other package managers.
<details><summary><b>Steam Deck</b> (click to show)</summary>
<details open><summary><b>Steam Deck</b> (click to show)</summary>
Desktop Mode on the Steam Deck uses `pacman`. It also requires a few steps.
@ -134,40 +172,27 @@ yay -S base-devel mercurial subversion
</details>
</TabItem>
<TabItem value="m" label="MacOS">
After installing mercurial and subversion, install NodeJS.
On MacOS, install using Homebrew.
:::note
0) Open a terminal window and install Homebrew:
[The official NodeJS site](https://nodejs.org/en/download/) provides installers
for "LTS" and "Current" releases. The "LTS" version should be installed.
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```
1) Close the window, open a new terminal window, and disable analytics:
```bash
brew analytics off
```
To confirm analytics are disabled, run
```bash
brew analytics state
```
It should print `Analytics are disabled.`
2) Install Mercurial and Subversion:
```bash
brew install mercurial subversion
```
:::
</TabItem>
</Tabs>
### Build from source tree
0) Clone the project:
```bash
git clone https://git.sheetjs.com/sheetjs/sheetjs
cd sheetjs
```
1) Install NodeJS modules for building the scripts
```bash
@ -206,21 +231,82 @@ cd modules; make; cd ..
make dist
```
4) (For Deno testing) Install Deno:
### Reproduce official builds
4) Run `git log` and search for the commit that matches a particular release
version. For example, version `0.19.1` can be found with:
```bash
curl -fsSL https://deno.land/install.sh | sh
git log | grep -B4 "version bump 0.19.1"
```
5) (For Bun testing) Install Bun:
The output should look like:
```bash
curl https://bun.sh/install | bash
$ git log | grep -B4 "version bump 0.19.1"
# highlight-next-line
commit 51a861900092bfc01b2fa9960d4c932dcbeb6925 <-- this is the commit hash
Author: SheetJS <dev@sheetjs.com>
Date: Thu Nov 17 04:35:34 2022 -0500
version bump 0.19.1
```
</TabItem>
</Tabs>
5) Switch to that commit:
```bash
git checkout 51a861900092bfc01b2fa9960d4c932dcbeb6925
```
6) Run the full build sequence
```bash
make clean
cd modules; make; cd ..
make
make dist
```
7) To verify that the files are intact, use `md5sum` (`md5` on MacOS).
The local checksum for the browser script can be computed with:
```bash
$ md5sum dist/xlsx.full.min.js
00b46a9f2d30ddc69780ab8049d6809e dist/xlsx.full.min.js
```
The checksum for the CDN version can be computed with:
```bash
curl -L https://cdn.sheetjs.com/xlsx-0.19.1/package/dist/xlsx.full.min.js | md5sum -
00b46a9f2d30ddc69780ab8049d6809e -
```
The two hashes should match.
8) To return to the HEAD commit, run
```bash
git checkout HEAD
```
### Test in web browsers
9) Start local server:
```bash
make ctestserv
```
The terminal will display a port number. For example:
```
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)
```
10) Open a browser window and access `http://localhost:8000`, replacing `8000`
with the port number from the terminal window.
## Development

@ -183,6 +183,10 @@ const config = {
{ from: '/docs/demos/aws', to: '/docs/demos/cloud/aws/' },
{ from: '/docs/demos/azure', to: '/docs/demos/cloud/azure/' },
{ from: '/docs/demos/netsuite', to: '/docs/demos/cloud/netsuite/' },
/* extensions */
{ from: '/docs/demos/extendscript', to: '/docs/demos/extensions/extendscript/' },
{ from: '/docs/demos/excelapi', to: '/docs/demos/extensions/excelapi/' },
{ from: '/docs/demos/chromium', to: '/docs/demos/extensions/chromium/' },
]
}]
]