diff --git a/docz/docs/03-demos/24-extendscript.md b/docz/docs/03-demos/10-extensions/01-extendscript.md similarity index 98% rename from docz/docs/03-demos/24-extendscript.md rename to docz/docs/03-demos/10-extensions/01-extendscript.md index 3eb623d..aa64011 100644 --- a/docz/docs/03-demos/24-extendscript.md +++ b/docz/docs/03-demos/10-extensions/01-extendscript.md @@ -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) - diff --git a/docz/docs/03-demos/28-chromium.md b/docz/docs/03-demos/10-extensions/02-chromium.md similarity index 97% rename from docz/docs/03-demos/28-chromium.md rename to docz/docs/03-demos/10-extensions/02-chromium.md index ab65f93..61a6005 100644 --- a/docz/docs/03-demos/28-chromium.md +++ b/docz/docs/03-demos/10-extensions/02-chromium.md @@ -1,5 +1,7 @@ --- -title: Chrome Extensions +title: Chrome and Chromium +pagination_prev: demos/server +pagination_next: demos/gsheet --- :::warning diff --git a/docz/docs/03-demos/26-excelapi.md b/docz/docs/03-demos/10-extensions/03-excelapi.md similarity index 89% rename from docz/docs/03-demos/26-excelapi.md rename to docz/docs/03-demos/10-extensions/03-excelapi.md index 9080821..8d1fe6f 100644 --- a/docz/docs/03-demos/26-excelapi.md +++ b/docz/docs/03-demos/10-extensions/03-excelapi.md @@ -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 @@ -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 + +::: diff --git a/docz/docs/03-demos/10-extensions/_category_.json b/docz/docs/03-demos/10-extensions/_category_.json new file mode 100644 index 0000000..6cac06b --- /dev/null +++ b/docz/docs/03-demos/10-extensions/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "App Extensions", + "position": 10, + "collapsed": false +} \ No newline at end of file diff --git a/docz/docs/03-demos/10-extensions/index.md b/docz/docs/03-demos/10-extensions/index.md new file mode 100644 index 0000000..8268e44 --- /dev/null +++ b/docz/docs/03-demos/10-extensions/index.md @@ -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: + + diff --git a/docz/docs/03-demos/25-gsheet.md b/docz/docs/03-demos/25-gsheet.md index c5665dc..52196dd 100644 --- a/docz/docs/03-demos/25-gsheet.md +++ b/docz/docs/03-demos/25-gsheet.md @@ -1,5 +1,6 @@ --- title: Google Sheets +pagination_prev: demos/extensions/index --- import Tabs from '@theme/Tabs'; diff --git a/docz/docs/09-miscellany/05-contributing.md b/docz/docs/09-miscellany/05-contributing.md index aa59cdb..71790c9 100644 --- a/docz/docs/09-miscellany/05-contributing.md +++ b/docz/docs/09-miscellany/05-contributing.md @@ -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'; -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 +``` - + -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: - - + -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. -
Steam Deck (click to show) +
Steam Deck (click to show) Desktop Mode on the Steam Deck uses `pacman`. It also requires a few steps. @@ -134,40 +172,27 @@ yay -S base-devel mercurial subversion
- - +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 -``` +::: +### 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 +Date: Thu Nov 17 04:35:34 2022 -0500 + + version bump 0.19.1 ``` - - +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 diff --git a/docz/docusaurus.config.js b/docz/docusaurus.config.js index 037a1b6..add5303 100644 --- a/docz/docusaurus.config.js +++ b/docz/docusaurus.config.js @@ -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/' }, ] }] ]