docs.sheetjs.com/docz/docs/03-demos/06-desktop/03-wails.md

390 lines
11 KiB
Markdown
Raw Normal View History

2023-01-05 03:57:48 +00:00
---
title: Wails
2023-06-20 01:21:34 +00:00
sidebar_label: Wails
description: Build data-intensive desktop apps using Wails. Seamlessly integrate spreadsheets into your app using SheetJS. Modernize Excel-powered business processes with confidence.
2023-01-05 23:33:49 +00:00
pagination_prev: demos/mobile/index
2023-02-28 11:40:44 +00:00
pagination_next: demos/data/index
2023-01-05 03:57:48 +00:00
sidebar_position: 3
sidebar_custom_props:
summary: Webview + Go Backend
---
2023-06-20 01:21:34 +00:00
# Spreadsheet-Powered Wails Apps
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2023-01-05 03:57:48 +00:00
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
2023-04-30 12:27:09 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
[Wails](https://wails.io/) is a modern toolkit for building desktop apps. Wails
apps pair a Go-powered backend with a JavaScript-powered frontend[^1].
[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.
This demo uses Wails and SheetJS to pull data from a spreadsheet and display the
data in the app. We'll explore how to load SheetJS in a Wails app and exchange
file data between the JavaScript frontend and Go backend.
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
The ["Complete Example"](#complete-example) section covers a complete desktop
app to read and write workbooks. The app will look like the screenshots below:
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
<table><thead><tr>
2023-06-20 01:21:34 +00:00
<th><a href="#complete-example">Windows</a></th>
2023-01-09 05:08:30 +00:00
<th><a href="#complete-example">macOS</a></th>
<th><a href="#complete-example">Linux</a></th>
</tr></thead><tbody><tr><td>
2023-01-05 03:57:48 +00:00
2023-03-19 06:02:55 +00:00
![Win10 screenshot](pathname:///wails/win10.png)
</td><td>
2023-01-09 05:08:30 +00:00
![macOS screenshot](pathname:///wails/macos.png)
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
</td><td>
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
![Linux screenshot](pathname:///wails/linux.png)
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
</td></tr></tbody></table>
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
:::info
This demo assumes some familiarity with JavaScript and with Go. If you would
prefer a pure JavaScript solution, the [Electron](/docs/demos/desktop/electron)
platform provides many native features out of the box.
:::
2023-02-12 08:15:17 +00:00
## Integration Details
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
The [SheetJS NodeJS Module](/docs/getting-started/installation/nodejs) can be
installed in the `frontend` folder and imported in frontend scripts.
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
:::caution
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
Wails currently does not provide the equivalent of NodeJS `fs` module.
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
Reading and writing raw file data must be implemented in native Go code.
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
:::
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
This demo includes native Go code for showing dialogs and reading and writing
files. When sending data between Go and JavaScript code, the raw files are
encoded as Base64 strings.
2023-01-05 03:57:48 +00:00
### Reading Files
2023-06-20 01:21:34 +00:00
When the user clicks the "Import File" button, the frontend tells the Go backend
to read data. The user will be presented with a file picker to select a file to
read. The Go backend will read the data, encode as a Base64 string, and send the
result to the frontend.
The frontend will parse the data using the SheetJS `read` method[^2], generate
HTML tables with `sheet_to_html`[^3], and display the tables on the frontend.
The following diagram summarizes the steps:
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
```mermaid
sequenceDiagram
actor User
2023-06-20 01:21:34 +00:00
participant JS as Frontend (JS)
participant Go as Backend (Go)
2023-01-09 05:08:30 +00:00
User->>JS: click button
JS->>Go: ask for data
Note over Go: Show Open Dialog
Note over Go: Read File Bytes
Note over Go: Generate Base64
Go->>JS: return data
2023-06-20 01:21:34 +00:00
Note over JS: Parse Data<br/>`read`
Note over JS: Display Table<br/>`sheet_to_html`
2023-01-09 05:08:30 +00:00
JS->>User: app shows data
```
2023-01-05 03:57:48 +00:00
#### Go
2023-06-20 01:21:34 +00:00
The Wails runtime provides the cross-platform `OpenFileDialog` function[^4] to
show a file picker. The Go standard library provides methods for reading data
from the selected file[^5] and encoding in a Base64 string[^6]
2023-01-05 03:57:48 +00:00
```go
import (
"context"
// highlight-start
"encoding/base64"
2023-06-20 01:21:34 +00:00
"os"
2023-01-05 03:57:48 +00:00
"github.com/wailsapp/wails/v2/pkg/runtime"
// highlight-end
)
type App struct {
ctx context.Context
}
// ReadFile shows an open file dialog and returns the data as Base64 string
func (a *App) ReadFile() string {
// highlight-next-line
selection, err := runtime.OpenFileDialog(a.ctx, runtime.OpenDialogOptions{
Title: "Select File",
Filters: []runtime.FileFilter{
{ DisplayName: "Excel Workbooks (*.xlsx)", Pattern: "*.xlsx", },
// ... more filters for more file types
},
})
if err != nil { return "" } // The demo app shows an error message
// highlight-next-line
2023-06-20 01:21:34 +00:00
data, err := os.ReadFile(selection)
2023-01-05 03:57:48 +00:00
if err != nil { return "" } // The demo app shows an error message
// highlight-next-line
return base64.StdEncoding.EncodeToString(data)
}
```
#### JS
2023-06-20 01:21:34 +00:00
Wails will automatically create bindings for use in JS. The `App` binding module
will export the function `ReadFile`.
2023-01-05 03:57:48 +00:00
```js title="frontend/src/App.svelte"
import { read, utils } from 'xlsx';
2023-01-09 05:08:30 +00:00
import { ReadFile } from '../wailsjs/go/main/App';
2023-01-05 03:57:48 +00:00
async function importFile(evt) {
// highlight-start
2023-06-20 01:21:34 +00:00
/* call the native Go function and receive a base64 string */
2023-01-09 05:08:30 +00:00
const b64 = await ReadFile();
2023-06-20 01:21:34 +00:00
/* parse the base64 string with SheetJS */
2023-01-05 03:57:48 +00:00
const wb = read(b64, { type: "base64" });
// highlight-end
2023-06-20 01:21:34 +00:00
2023-01-05 03:57:48 +00:00
const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet
2023-06-20 01:21:34 +00:00
return utils.sheet_to_html(ws); // generate HTML table
2023-01-05 03:57:48 +00:00
}
```
### Writing Files
2023-06-20 01:21:34 +00:00
:::info
The SheetJS `write` method[^7] can write spreadsheets in a number of formats[^8]
including XLSX, XLSB, XLS, and NUMBERS. It expects a `bookType` option. This
means the frontend needs to know the output file name before creating the file.
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
:::
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
When the user clicks the "Export File" button, the frontend asks the Go backend
for the output filename and path. The user will be presented with a file picker
to select the output folder and workbook type. The backend will send the name
to the frontend.
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
The frontend will generate a workbook object from the table using the SheetJS
`table_to_book` method[^9]. The SheetJS `write` method[^10] will generate a
Base64 string from the data.
The frontend will send the Base64 string to the backend. The backend will write
the data to a file in the selected folder.
2023-01-05 03:57:48 +00:00
2023-01-09 05:08:30 +00:00
```mermaid
sequenceDiagram
actor User
2023-06-20 01:21:34 +00:00
participant JS as Frontend (JS)
participant Go as Backend (Go)
2023-01-09 05:08:30 +00:00
User->>JS: click button
JS->>Go: ask for path
Note over Go: Show Save Dialog
Go->>JS: path to save file
2023-06-20 01:21:34 +00:00
Note over JS: Read from Table<br/>`table_to_book`
Note over JS: Write Workbook<br/>`write`
2023-01-09 05:08:30 +00:00
JS->>Go: base64-encoded bytes
2023-06-20 01:21:34 +00:00
Note over Go: Decode Data
Note over Go: Write to File
2023-01-09 05:08:30 +00:00
Go->>JS: write finished
JS->>User: alert
```
2023-01-05 03:57:48 +00:00
##### Go
Two Go functions will be exposed.
2023-06-20 01:21:34 +00:00
- `SaveFile` will show the file picker and return the path. It will use the
cross-platform `SaveFileDialog` function[^11].
2023-01-05 03:57:48 +00:00
```go
import (
"context"
2023-01-09 05:08:30 +00:00
// highlight-next-line
2023-01-05 03:57:48 +00:00
"github.com/wailsapp/wails/v2/pkg/runtime"
)
type App struct {
ctx context.Context
}
func (a *App) SaveFile() string {
// highlight-next-line
selection, err := runtime.SaveFileDialog(a.ctx, runtime.SaveDialogOptions{
Title: "Select File",
DefaultFilename: "SheetJSWails.xlsx",
Filters: []runtime.FileFilter{
{ DisplayName: "Excel Workbooks (*.xlsx)", Pattern: "*.xlsx", },
// ... more filters for more file types
},
})
if err != nil { return "" } // The demo app shows an error message
return selection
}
```
2023-06-20 01:21:34 +00:00
- `WriteFile` performs the file write given a Base64 string and file path. The
Go standard library provides methods for decoding Base64 strings[^12] and
writing data to the filesystem[^13]
2023-01-05 03:57:48 +00:00
```go
import (
"context"
// highlight-start
"encoding/base64"
2023-06-20 01:21:34 +00:00
"os"
2023-01-05 03:57:48 +00:00
// highlight-end
)
type App struct {
ctx context.Context
}
func (a *App) WriteFile(b64 string, path string) {
// highlight-start
buf, _ := base64.StdEncoding.DecodeString(b64);
2023-06-20 01:21:34 +00:00
_ = os.WriteFile(path, buf, 0644);
2023-01-05 03:57:48 +00:00
// highlight-end
}
```
#### JS
2023-06-20 01:21:34 +00:00
Wails will automatically create bindings for use in JS. The `App` binding module
will export the functions `SaveFile` and `WriteFile`:
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
```js title="frontend/src/App.svelte"
2023-01-05 03:57:48 +00:00
import { utils, write } from 'xlsx';
2023-01-09 05:08:30 +00:00
import { SaveFile, WriteFile } from '../wailsjs/go/main/App';
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
async function exportFile(table_element) {
2023-01-05 03:57:48 +00:00
/* generate workbook */
2023-06-20 01:21:34 +00:00
const wb = utils.table_to_book(table_element);
2023-01-05 03:57:48 +00:00
/* show save picker and get path */
2023-01-09 05:08:30 +00:00
const path = await SaveFile();
2023-01-05 03:57:48 +00:00
2023-06-20 01:21:34 +00:00
/* get the file extension -> bookType */
const bookType = path.slice(path.lastIndexOf(".")+1);
/* generate base64 string */
const b64 = write(wb, { bookType: bookType, type: "base64" });
2023-01-05 03:57:48 +00:00
/* write to file */
2023-01-09 05:08:30 +00:00
await WriteFile(b64, path);
2023-01-05 03:57:48 +00:00
}
```
2023-01-09 05:08:30 +00:00
## Complete Example
2023-02-12 08:15:17 +00:00
:::note
2023-04-30 12:27:09 +00:00
This demo was tested against Wails `v2.4.1` on 2023 April 30 using
2023-01-09 05:08:30 +00:00
the Svelte TypeScript starter.
2023-02-12 08:15:17 +00:00
:::
2023-06-20 01:21:34 +00:00
0) Read the Wails "Getting Started" guide[^14] and install dependencies.
<details><summary><b>Installation Notes</b> (click to show)</summary>
Wails will require:
- A recent version of [Go](https://go.dev/doc/install).
- The "LTS" version of [NodeJS](https://nodejs.org/en/download).
After installing both, run the following command to install Wails:
```bash
go install github.com/wailsapp/wails/v2/cmd/wails@latest
```
Once that finishes, run the following command in a new terminal window:
```bash
wails doctor
```
The output will include a `# Diagnosis` section. It should display:
```
# Diagnosis
Your system is ready for Wails development!
```
If a required dependency is missing, it will be displayed.
:::note
None of the optional packages are required for building and running this demo.
:::
</details>
2023-01-09 05:08:30 +00:00
1) Create a new Wails app:
```bash
wails init -n sheetjs-wails -t svelte-ts
```
2) Enter the directory:
```bash
cd sheetjs-wails
```
3) Install front-end dependencies:
2023-04-30 12:27:09 +00:00
<CodeBlock language="bash">{`\
2023-01-09 05:08:30 +00:00
cd frontend
curl -L -o src/assets/logo.png https://sheetjs.com/sketch1024.png
2023-04-30 12:27:09 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz
cd ..`}
</CodeBlock>
2023-01-09 05:08:30 +00:00
4) Download source files:
- Download [`app.go`](pathname:///wails/app.go) and replace `app.go`
- Download [`App.svelte`](pathname:///wails/App.svelte) and replace
`frontend/src/App.svelte`
```bash
curl -L -o app.go https://docs.sheetjs.com/wails/app.go
curl -L -o frontend/src/App.svelte https://docs.sheetjs.com/wails/App.svelte
```
5) Build the app with
```bash
wails build
```
At the end, it will print the path to the generated program. Run the program!
2023-06-20 01:21:34 +00:00
[^1]: See ["How does it Work?"](https://wails.io/docs/howdoesitwork) in the Wails documentation.
2023-06-25 09:36:58 +00:00
[^2]: See [`read` in "Reading Files"](/docs/api/parse-options)
2023-06-20 01:21:34 +00:00
[^3]: See [`sheet_to_html` in "Utilities"](/docs/api/utilities/html#html-table-output)
[^4]: See [`OpenFileDialog`](https://wails.io/docs/reference/runtime/dialog#openfiledialog) in the Wails documentation.
[^5]: See [`ReadFile`](https://pkg.go.dev/os#ReadFile) in the Go documentation
[^6]: See [`EncodeToString`](https://pkg.go.dev/encoding/base64#Encoding.EncodeToString) in the Go documentation
[^7]: See [`write` in "Writing Files"](/docs/api/write-options)
[^8]: See ["Supported Output Formats" type in "Writing Files"](/docs/api/write-options#supported-output-formats)
[^9]: See ["HTML Table Input" in "Utilities"](/docs/api/utilities/html#create-new-sheet)
[^10]: See [`write` in "Writing Files"](/docs/api/write-options)
[^11]: See [`SaveFileDialog`](https://wails.io/docs/reference/runtime/dialog#savefiledialog) in the Wails documentation.
[^12]: See [`DecodeString`](https://pkg.go.dev/encoding/base64#Encoding.DecodeString) in the Go documentation
[^13]: See [`WriteFile`](https://pkg.go.dev/os#WriteFile) in the Go documentation
[^14]: See ["Installation"](https://wails.io/docs/gettingstarted/installation) in the Wails documentation.