docs.sheetjs.com/docz/docs/03-demos/12-static/01-lume.md

246 lines
6.4 KiB
Markdown
Raw Normal View History

2023-01-15 03:36:13 +00:00
---
2023-08-17 20:30:13 +00:00
title: Illuminating Data with Lume
2023-06-25 19:57:03 +00:00
sidebar_label: Lume
description: Make static websites from spreadsheets using Lume. Seamlessly integrate data into your website using SheetJS. Illuminate data without leaving the comfort of Excel.
2023-02-28 11:40:44 +00:00
pagination_prev: demos/net/index
pagination_next: demos/mobile/index
2023-01-15 03:36:13 +00:00
sidebar_custom_props:
type: native
---
2023-06-25 19:57:03 +00:00
[Lume](https://lume.land/) is a lightweight unopinionated static site generator.
It has a rich ecosystem of JavaScript-powered plugins[^1]
2023-01-15 03:36:13 +00:00
2023-06-25 19:57:03 +00:00
[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.
This demo uses Lume and SheetJS (through the official "Sheets" plugin) to pull
data from a spreadsheet and display the content in an HTML table.
The ["Complete Example"](#complete-example) section includes a complete website
powered by an XLSX spreadsheet.
2023-01-15 03:36:13 +00:00
2023-03-14 08:38:47 +00:00
## Integration Details
2023-06-25 19:57:03 +00:00
The official "Sheets" plugin[^2] uses SheetJS to load data from spreadsheets.
Under the hood, the plugin uses the SheetJS `read`[^3] method to parse files and
the `sheet_to_json`[^4] method to generate arrays of objects.
Lume supports refreshing data during development. The generated static sites
include the raw data without referencing the underlying spreadsheet files.
2023-03-14 08:38:47 +00:00
### Installation
The `sheets` plugin can be imported and invoked in `_config.ts`:
```ts title="_config.ts"
import lume from "lume/mod.ts";
// highlight-next-line
import sheets from "lume/plugins/sheets.ts";
const site = lume();
// highlight-next-line
site.use(sheets());
export default site;
```
2023-06-25 19:57:03 +00:00
:::info pass
2023-03-14 08:38:47 +00:00
2023-06-25 19:57:03 +00:00
The lines are automatically added if `sheets` plugin is enabled during setup.
2023-03-14 08:38:47 +00:00
:::
2023-06-25 19:57:03 +00:00
### Usage
2023-03-14 08:38:47 +00:00
Spreadsheet files added in the `_data` subdirectory are accessible from template
files using the name stem.
2023-06-25 19:57:03 +00:00
For example, [`pres.xlsx`](https://sheetjs.com/pres.xlsx) can be accessed using
the variable `pres` in a template.
2023-03-14 08:38:47 +00:00
#### Single-Sheet Workbooks
When a workbook has one worksheet, the data is an array of row objects:
```liquid title="single.njk"
2023-12-05 03:46:54 +00:00
<table><thead><tr><th>Name</th><th>Index</th></tr></thead>
2023-03-14 08:38:47 +00:00
<tbody>
{% for row in pres %}
<tr>
<td>{{ row.Name }}</td>
<td>{{ row.Index }}</td>
</tr>
{% endfor %}
</tbody>
</table>
```
#### Multi-Sheet Workbooks
_Reading the First Worksheet_
The `sheets` plugin accepts an options argument. If the `sheets` property is
set to `"first"`, then the plugin will expose row objects for the first sheet:
```ts title="_config.ts"
// the first sheet of each file will be parsed and converted to row objects
site.use(sheets({ sheets: "first" }));
```
_Reading all Worksheets_
The default behavior, when workbooks have multiple sheets, is to present objects
whose keys are worksheet names and whose values are arrays of row objects.
2023-06-25 19:57:03 +00:00
For example, if `pres.xlsx` had a sheet named `"Presidents"` and another sheet
named `"VicePresidents"`, then the following snippet would print data from the
`"Presidents"` sheet:
2023-03-14 08:38:47 +00:00
```liquid title="multi.njk"
2023-12-05 03:46:54 +00:00
<table><thead><tr><th>Name</th><th>Index</th></tr></thead>
2023-03-14 08:38:47 +00:00
<tbody>
{% for row in pres["Presidents"] %}
<tr>
<td>{{ row.Name }}</td>
<td>{{ row.Index }}</td>
</tr>
{% endfor %}
</tbody>
</table>
```
2023-06-25 19:57:03 +00:00
#### File Formats
As explained in the official plugin documentation[^5], the loader loads XLSX.
NUMBERS, and CSV files. Other extensions can be added through the `extensions`
property in the argument to the `sheets` plugin:
```ts
site.use(sheets({
// highlight-next-line
extensions: [".xlsx", ".xlsb", ".xls"]
}));
```
2023-03-14 08:38:47 +00:00
## Complete Example
2023-01-15 03:36:13 +00:00
2023-12-05 03:46:54 +00:00
:::note Tested Deployments
2023-01-15 03:36:13 +00:00
2024-03-18 08:24:41 +00:00
This demo was tested in the following environments:
| Lume | Date |
|:---------|:-----------|
| `1.19.4` | 2024-03-16 |
| `2.1.2` | 2024-03-16 |
2023-01-15 03:36:13 +00:00
This example uses the Nunjucks template format. Lume plugins support additional
template formats, including Markdown and JSX.
:::
2023-06-25 19:57:03 +00:00
### Initial Setup
0) Install Deno[^6]
2023-01-15 03:36:13 +00:00
1) Create a stock site:
```bash
mkdir -p sheetjs-lume
cd sheetjs-lume
2024-03-18 08:24:41 +00:00
deno run -Ar https://deno.land/x/lume@v2.1.2/init.ts
2023-01-15 03:36:13 +00:00
```
When prompted, enter the following options:
2023-03-14 08:38:47 +00:00
- `Choose the configuration file format`: select `_config.ts`
- `Do you want to install some plugins now?`: select `Yes`
2024-03-18 08:24:41 +00:00
- `Select the plugins to install`: select `sheets` and `nunjucks`
- `Do you want to setup a CMS?`: select `Maybe later`
2023-01-15 03:36:13 +00:00
The project will be configured and modules will be installed.
2024-03-18 08:24:41 +00:00
:::note pass
The `nunjucks` plugin was included by default in Lume version 1.
:::
2) Download https://sheetjs.com/pres.xlsx and place in a `_data` subfolder:
2023-01-15 03:36:13 +00:00
```bash
mkdir -p _data
2023-06-25 19:57:03 +00:00
curl -L -o _data/pres.xlsx https://sheetjs.com/pres.xlsx
2023-01-15 03:36:13 +00:00
```
2023-06-25 19:57:03 +00:00
3) Create a `index.njk` file that references the file:
2023-01-15 03:36:13 +00:00
```liquid title="index.njk"
<h2>Presidents</h2>
2023-12-05 03:46:54 +00:00
<table><thead><tr><th>Name</th><th>Index</th></tr></thead>
2023-01-15 03:36:13 +00:00
<tbody>
2023-03-14 08:38:47 +00:00
{% for row in pres %}
2023-01-15 03:36:13 +00:00
<tr>
<td>{{ row.Name }}</td>
<td>{{ row.Index }}</td>
</tr>
2023-03-14 08:38:47 +00:00
{% endfor %}
2023-01-15 03:36:13 +00:00
</tbody>
</table>
```
2023-12-05 03:46:54 +00:00
:::note pass
Since the file name is `pres.xlsx`, the parameter name is `pres`.
:::
2023-06-25 19:57:03 +00:00
### Live Refresh
2023-01-15 03:36:13 +00:00
4) Run the development server:
```bash
2023-06-25 19:57:03 +00:00
deno task serve --port 7262
2023-01-15 03:36:13 +00:00
```
2023-12-05 03:46:54 +00:00
To verify the site, access the "Local" URL (typically `http://localhost:7262`)
from a web browser. The page will show the contents of the spreadsheet.
5) While the server is running, open `_data/pres.xlsx` in a spreadsheet editor.
2023-04-19 08:50:07 +00:00
2023-12-05 03:46:54 +00:00
Set cell `A7` to "SheetJS Dev" and set `B7` to `47`. Save the spreadsheet.
2023-04-19 08:50:07 +00:00
2023-10-15 02:39:07 +00:00
After saving the spreadsheet, the page will refresh and show the new contents.
2023-04-19 08:50:07 +00:00
2023-06-25 19:57:03 +00:00
### Static Site
2023-01-15 03:36:13 +00:00
2023-06-25 19:57:03 +00:00
6) Stop the server (press `CTRL+C` in the terminal window) and run
2023-01-15 03:36:13 +00:00
```bash
deno task lume
```
2023-06-25 19:57:03 +00:00
This will create a static site in the `_site` folder
7) Test the generated site by running
2023-01-15 03:36:13 +00:00
```bash
npx http-server _site
```
2023-06-25 19:57:03 +00:00
The program will display a URL (typically `http://localhost:8080`). Accessing
the page will show the contents of the spreadsheet.
View the page source and confirm that the page only includes an HTML table. No
scripts are included in this page.
2023-01-15 03:36:13 +00:00
This site is self-contained and ready for deployment!
2023-06-25 19:57:03 +00:00
[^1]: See ["Plugins"](https://lume.land/plugins/?status=all) in the Lume documentation
[^2]: See ["Sheets"](https://lume.land/plugins/sheets/) in the Lume documentation
[^3]: See [`read` in "Reading Files"](/docs/api/parse-options)
[^4]: See [`sheet_to_json` in "Utilities"](/docs/api/utilities/array#array-output)
[^5]: See ["Formats"](https://lume.land/plugins/sheets/#formats) in the Lume documentation
[^6]: See ["Installation"](https://deno.com/manual/getting_started/installation) in the Deno documentation