2024-12-26 16:51:25 +00:00
---
2025-01-06 02:51:20 +00:00
title: Sheets in UI5 Sites
sidebar_label: OpenUI5 / SAPUI5
2024-12-26 16:51:25 +00:00
description: Build enterprise-grade applications with OpenUI5. Seamlessly integrate spreadsheets into your app using SheetJS. Bring Excel-powered workflows and data to the modern web.
pagination_prev: demos/index
pagination_next: demos/grid/index
sidebar_position: 10
---
import current from '/version.js';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CodeBlock from '@theme/CodeBlock';
2025-01-06 02:51:20 +00:00
[OpenUI5 ](https://openui5.org/ ) is a JavaScript framework for building
enterprise-ready web applications. It is compatible with the SAPUI5 framework.
2024-12-26 16:51:25 +00:00
[SheetJS ](https://sheetjs.com ) is a JavaScript library for reading and writing
data from spreadsheets.
2025-01-07 16:45:50 +00:00
This demo shows how to handle spreadsheet data in OpenUI5 apps using SheetJS.
You'll learn how to load spreadsheet files, process their data, and generate
new spreadsheet exports.
2024-12-26 16:51:25 +00:00
2025-01-06 02:51:20 +00:00
:::info pass
[Docs Issue #20 ](https://git.sheetjs.com/sheetjs/docs.sheetjs.com/issues/20 )
includes a complete example starting from the OpenUI5 "Worklist App Tutorial".
:::
2024-12-26 16:51:25 +00:00
## Installation
2025-01-15 18:43:08 +00:00
SheetJS libraries conform to the UI5 ECMAScript requirements[^1]. SheetJS
2025-01-06 02:51:20 +00:00
libraries can be loaded in a UI5 site at different points in the app lifecycle.
2024-12-26 16:51:25 +00:00
2025-01-15 18:43:08 +00:00
#### HTML {#installation-html}
2024-12-26 16:51:25 +00:00
2025-01-06 02:51:20 +00:00
UI5 is typically loaded in a `SCRIPT` tag in `webapp/index.html` . Similarly,
[SheetJS Standalone scripts ](/docs/getting-started/installation/standalone )
2025-01-15 18:43:08 +00:00
can be loaded with a `SCRIPT` tag in the same HTML page:
2025-01-06 02:51:20 +00:00
< CodeBlock language = "html" value = "html" > {`\
< script src = "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js" > < / script >
`}
< / CodeBlock >
This will expose the `XLSX` global object, which includes the functions listed
in the ["API Reference" ](/docs/api/ ) section of the documentation.
:::caution pass
2025-01-15 18:43:08 +00:00
**The SheetJS Standalone script must be loaded before the UI5 bootstrap script**:
2025-01-06 02:51:20 +00:00
2025-01-15 18:43:08 +00:00
< CodeBlock language = "html" value = "html" title = "webapp/index.html (loading the SheetJS standalone script)" > {`\
2025-01-06 02:51:20 +00:00
< head >
< meta charset = "utf-8" >
< title > UI5 Walkthrough< / title >
2025-01-15 18:43:08 +00:00
<!-- The SheetJS Standalone script must be loaded before the UI5 bootstrap -->
2025-01-06 02:51:20 +00:00
< script src = "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js" > < / script >
2025-01-15 18:43:08 +00:00
<!-- UI5 bootstrap script -->
2025-01-06 02:51:20 +00:00
< script
id="sap-ui-bootstrap"
src="resources/sap-ui-core.js"
...(other attributes)...
2025-01-15 18:43:08 +00:00
>< / script >
2025-01-06 02:51:20 +00:00
< / head >
`}
2024-12-26 16:51:25 +00:00
< / CodeBlock >
2025-01-06 02:51:20 +00:00
:::
2025-01-15 18:43:08 +00:00
#### UI5 Module {#installation-define}
2025-01-06 02:51:20 +00:00
The [SheetJS Standalone scripts ](/docs/getting-started/installation/standalone )
comply with AMD `define` semantics. They support `sap.ui.define` out of the box.
If the SheetJS Standalone script is saved to `webapp/xlsx.full.min.js` , the base
2025-01-15 18:43:08 +00:00
script `webapp/index.js` can load the `./xlsx.full.min` dependency:
2025-01-06 02:51:20 +00:00
2025-01-15 18:43:08 +00:00
```js title="webapp/index.js (loading the SheetJS dependency)"
2025-01-06 02:51:20 +00:00
sap.ui.define([
// highlight-next-line
"./xlsx.full.min", // relative path to script, without the file extension
/* ... other libraries ... */
2025-01-15 18:43:08 +00:00
], function (
2025-01-06 02:51:20 +00:00
// highlight-next-line
_XLSX // !! NOTE: this is not XLSX! A different variable name must be used
/* ... variables for the other libraries ... */,
) {
// highlight-next-line
alert(XLSX.version); // use XLSX in the callback
});
```
2024-12-26 16:51:25 +00:00
2025-01-06 02:51:20 +00:00
:::info pass
In some deployments, the function argument was `undefined` .
The standalone scripts add `window.XLSX` , so it is recommended to use `_XLSX`
in the function arguments and access the library with `XLSX` in the callback.
:::
2024-12-26 16:51:25 +00:00
## Internal State
The various SheetJS APIs work with various data shapes. The preferred state
depends on the application.
### JSON Model
2025-01-15 18:43:08 +00:00
The UI5 `JSONModel` [^2] is a client-side model implementation for JavaScript
object data. Think of it like a container that holds your spreadsheet data.
`JSONModel` provides powerful two-way data binding capabilities. UI5 will
automatically updates your webpage whenever the data changes. It will also
respond to changes when users interact with components in the webpage.
2024-12-26 16:51:25 +00:00
2025-01-15 18:43:08 +00:00
#### State {#json-state}
2024-12-26 16:51:25 +00:00
The example [presidents sheet ](https://docs.sheetjs.com/pres.xlsx ) has one
header row with "Name" and "Index" columns. The natural JS representation is an
2025-01-15 18:43:08 +00:00
object for each row, where the keys are specified in the first row:
2024-12-26 16:51:25 +00:00
< table >
< thead > < tr > < th > Spreadsheet< / th > < th > State< / th > < / tr > < / thead >
< tbody > < tr > < td >
< / td > < td >
```js
[
{ Name: "Bill Clinton", Index: 42 },
{ Name: "GeorgeW Bush", Index: 43 },
{ Name: "Barack Obama", Index: 44 },
{ Name: "Donald Trump", Index: 45 },
{ Name: "Joseph Biden", Index: 46 }
]
```
< / td > < / tr > < / tbody > < / table >
2025-01-15 18:43:08 +00:00
Here is a basic example of initializing a model. A more complete implementation
will be shown later.
2024-12-26 16:51:25 +00:00
2025-01-15 18:43:08 +00:00
```js title="UI5 JSONModel for rows of data"
2024-12-26 16:51:25 +00:00
sap.ui.define(["sap/ui/model/json/JSONModel"], function (JSONModel) {
2025-01-15 18:43:08 +00:00
// highlight-next-line
const oModel = new JSONModel({ presidents: [] });
2024-12-26 16:51:25 +00:00
});
```
2025-01-15 18:43:08 +00:00
#### Updating State {#json-update}
2024-12-26 16:51:25 +00:00
2025-01-15 18:43:08 +00:00
Starting from a spreadsheet file, the SheetJS [`read` ](/docs/api/parse-options )
method parses the data into a SheetJS workbook object[^6]. After selecting a
worksheet, the [`sheet_to_json` ](/docs/api/utilities/array#array-output ) method
generates row objects that can be assigned to the model.
2024-12-26 16:51:25 +00:00
2025-01-15 18:43:08 +00:00
Here is a sample flow diagram and method for downloading a workbook, generating
rows from the first worksheet, and updating a UI5 `JSONModel` :
2024-12-26 16:51:25 +00:00
```mermaid
flowchart LR
url[(Remote\nFile)]
ab[(Data\nArrayBuffer)]
wb(SheetJS\nWorkbook)
ws(SheetJS\nWorksheet)
aoo(array of\nobjects)
model((JSON\nModel))
url --> |fetch\n\n| ab
ab --> |read\n\n| wb
wb --> |wb.Sheets\nselect sheet| ws
ws --> |sheet_to_json\n\n| aoo
aoo --> |setProperty\nfrom model| model
2025-01-15 18:43:08 +00:00
linkStyle 1,2,3 color:blue,stroke:blue;
2024-12-26 16:51:25 +00:00
```
2025-01-15 18:43:08 +00:00
```js title="Download workbook, extract data from first worksheet, and update JSONModel"
2024-12-26 16:51:25 +00:00
_loadExcelFile: async function () {
/* Download from https://docs.sheetjs.com/pres.xlsx */
const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer();
2025-01-15 18:43:08 +00:00
2024-12-26 16:51:25 +00:00
// highlight-start
/* parse */
const wb = XLSX.read(f); // parse the array buffer
/* generate array of objects from first worksheet */
const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet
const data = XLSX.utils.sheet_to_json(ws); // generate objects
/* update JSONModel */
2025-01-15 18:43:08 +00:00
this.getView().getModel().setProperty("/presidents", data);
2024-12-26 16:51:25 +00:00
// highlight-end
}
```
2025-01-15 18:43:08 +00:00
#### Rendering Data {#json-render}
2024-12-26 16:51:25 +00:00
2025-01-15 18:43:08 +00:00
In UI5, the "Model-View-Controller"[^3] pattern is used to organize code and
separate concerns. The view defines the UI structure, the controller handles the
logic, and the model manages the data.
2024-12-26 16:51:25 +00:00
2025-01-15 18:43:08 +00:00
```xml title="Example View XML for displaying an array of objects"
2024-12-26 16:51:25 +00:00
< mvc:View >
2025-01-15 18:43:08 +00:00
< Page >
<!-- The Table component binds to the presidents array -->
<!-- highlight - next - line -->
< Table width = "300px" items = "{/presidents}" >
<!-- Column definitions specify the table structure -->
< columns >
< Column > < header > < Text text = "Name" / > < / header > < / Column >
< Column > < header > < Text text = "Value" / > < / header > < / Column >
< / columns >
<!-- ColumnListItem template defines how each row should be rendered -->
<!-- highlight - start -->
< items >
< ColumnListItem >
< cells >
< Text text = "{Name}" / >
< Text text = "{Index}" / >
< / cells >
< / ColumnListItem >
< / items >
<!-- highlight - end -->
< / Table >
< / Page >
2024-12-26 16:51:25 +00:00
< / mvc:View >
```
2025-01-15 18:43:08 +00:00
#### Exporting Data {#json-export}
2024-12-26 16:51:25 +00:00
The [`writeFile` ](/docs/api/write-options ) and [`json_to_sheet` ](/docs/api/utilities/array#array-of-objects-input )
functions simplify exporting data. They are typically used in event handlers attached to buttons or other elements.
A button press handler can generate a local file when clicked:
```mermaid
flowchart LR
state((oModel\ngetProperty))
ws(SheetJS\nWorksheet)
wb(SheetJS\nWorkbook)
file[(XLSX\nexport)]
state --> |json_to_sheet\n\n| ws
ws --> |book_new\nbook_append_sheet| wb
wb --> |writeFile\n\n| file
```
```js
/* get model data and export to XLSX */
2025-01-15 18:43:08 +00:00
onExport: function () {
2024-12-26 16:51:25 +00:00
const data = this.getView().getModel().getProperty("/presidents");
/* generate worksheet from model data */
// highlight-next-line
const ws = XLSX.utils.json_to_sheet(data);
/* create workbook and append worksheet */
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, "Data");
/* export to XLSX */
XLSX.writeFileXLSX(wb, "SheetJSOpenUI5AoO.xlsx");
}
```
#### Complete Component
This complete component example fetches a test file and displays the contents in a table.
When the export button is clicked, an event handler will export a file:
2025-01-07 16:45:50 +00:00
##### View Implementation {#view-implementation}
2024-12-26 16:51:25 +00:00
```xml title="webapp/view/Main.view.xml"
< mvc:View
controllerName="sheetjs.openui5.controller.Main"
displayBlock="true"
xmlns="sap.m"
xmlns:mvc="sap.ui.core.mvc"
xmlns:core="sap.ui.core"
core:require="{formatter: 'sheetjs/openui5/model/formatter'}">
< Page >
< VBox width = "auto" alignItems = "Start" >
< Table width = "300px" items = "{/presidents}" >
< columns >
< Column >
< header >
< Text text = "Name" / >
< / header >
< / Column >
< Column >
< header >
< Text text = "Value" / >
< / header >
< / Column >
< / columns >
< items >
< ColumnListItem >
< cells >
< Text text = "{Name}" / >
< Text text = "{Index}" / >
< / cells >
< / ColumnListItem >
< / items >
< / Table >
< Button text = "Export XLSX" press = ".onExport" / >
< / VBox >
< / Page >
< / mvc:View >
```
2025-01-07 16:45:50 +00:00
##### Controller Implementation {#controller-implementation}
2024-12-26 16:51:25 +00:00
```js title="webapp/controller/Main.controller.js"
sap.ui.define(
["./BaseController", "sap/ui/model/json/JSONModel"],
function (BaseController, JSONModel) {
"use strict";
return BaseController.extend("com.demo.xlsx.controller.Main", {
onInit: function () {
/* initialize model */
const oModel = new JSONModel({
presidents: [],
});
this.getView().setModel(oModel);
/* load data when component is initialized */
this._loadExcelFile();
},
_loadExcelFile: async function () {
const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer();
const wb = XLSX.read(f);
const ws = wb.Sheets[wb.SheetNames[0]];
const data = XLSX.utils.sheet_to_json(ws);
this.getView().getModel().setProperty("/presidents", data);
},
onExport: function () {
const data = this.getView().getModel().getProperty("/presidents");
const ws = XLSX.utils.json_to_sheet(data);
const wb = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, "Data");
XLSX.writeFileXLSX(wb, "SheetJSOpenUI5AoO.xlsx");
},
});
}
);
```
< details open >
< summary > < b > How to run the example< / b > (click to hide)< / summary >
:::note Tested Deployments
This demo was tested in the following environments:
| OpenUI5 | generator-easy-ui5 | Date |
|:--------|---------|---------|
2025-01-07 16:45:50 +00:00
| `1.131.1` | `3.8.1` | 2025-01-07 |
2024-12-26 16:51:25 +00:00
:::
1) Create a new site:
```bash
2025-01-07 16:45:50 +00:00
npm i --global generator-easy-ui5
2024-12-26 16:51:25 +00:00
npx yo easy-ui5 app
```
:::note Use the provided defaults:
- Application id: `sheetjs.openui5`
- Framework: `OpenUI5`
- Version: `1.131.1`
- Author: `SheetJS`
- Create new directory: `Y`
- Initialize git: `N`
:::
2) Install the dependencies and start server:
```bash
cd sheetjs.openui5
npm install
npm start
```
3) Open a web browser and access the displayed URL (`http://localhost:8080`)
4) Add SheetJS to your project by including this script tag in `webapp/index.html` :
< CodeBlock language = "html" value = "html" title = "webapp/index.html" >
{`< script src = "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js" > < / script > `}
< / CodeBlock >
2025-01-07 16:45:50 +00:00
5) Replace `webapp/view/Main.view.xml` with the complete [implementation above ](#view-implementation ).
6) Replace `webapp/controller/Main.controller.js` with the complete [implementation above ](#controller-implementation ).
2024-12-26 16:51:25 +00:00
The page will refresh and show a table with an Export button. Click the button and the page will
attempt to download `SheetJSOpenUI5AoO.xlsx` .
7) Build the site:
```bash
npm run build
```
The generated site will be placed in the `dist` folder.
8) Start a local web server:
```bash
npm run start:dist
```
Access the displayed URL (typically http://localhost:8080) with a web browser and test the page.
When the page loads, the app will fetch https://docs.sheetjs.com/pres.xlsx and
display the data from the first worksheet in a TABLE. The "Export XLSX" button
will generate a workbook that can be opened in a spreadsheet editor.
< / details >
### HTML
The main disadvantage of the Array of Objects approach is the specific nature
of the columns. For more general use, passing around an Array of Arrays works.
2025-01-06 02:51:20 +00:00
However, this does not handle merge cells[^4] well!
2024-12-26 16:51:25 +00:00
The [`sheet_to_html` ](/docs/api/utilities/html#html-table-output ) function generates HTML that is aware of merges and other worksheet
2025-01-06 02:51:20 +00:00
features. Using OpenUI5's `core:HTML` [^5] control, we can render this HTML directly. During export, we extract the table element from the
2024-12-26 16:51:25 +00:00
rendered HTML and use [`table_to_book` ](/docs/api/utilities/html#html-table-input ) to create a workbook that maintains all the worksheet
features.
2025-01-06 02:51:20 +00:00
In this example, the component directly renders the HTML table in the model through OpenUI5's `core:HTML` [^5] control. For export, we extract
2024-12-26 16:51:25 +00:00
the inner table from the rendered HTML using `getElementsByTagName("table")[1]` , then pass it to [`table_to_book` ](/docs/api/utilities/html#html-table-input )
to create a workbook that preserves all features.
2025-01-07 16:45:50 +00:00
##### View Implementation {#view-implementation-html}
2024-12-26 16:51:25 +00:00
```xml title="webapp/view/Main.view.xml"
< mvc:View
controllerName="sheetjs.openui5.controller.Main"
displayBlock="true"
xmlns="sap.m"
xmlns:mvc="sap.ui.core.mvc"
xmlns:core="sap.ui.core"
xmlns:html="http://www.w3.org/1999/xhtml">
< Page >
< content >
< core:HTML content = "{/tableHTML}" / >
< Button text = "Export XLSX" press = ".onExport" / >
< / content >
< / Page >
< / mvc:View >
```
2025-01-07 16:45:50 +00:00
##### Controller Implementation {#controller-implementation-html}
2024-12-26 16:51:25 +00:00
```js title="webapp/controller/Main.controller.js"
sap.ui.define(
[
"sap/ui/core/mvc/Controller",
"sap/ui/model/json/JSONModel"
],
function (Controller, JSONModel) {
"use strict";
return Controller.extend("sheetjs.openui5.controller.Main", {
onInit: function () {
/* the component state is an HTML string */
const oModel = new JSONModel({
tableHTML: "",
});
this.getView().setModel(oModel);
/* load data when component is initialized */
this._loadExcelFile();
},
_loadExcelFile: async function () {
const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer();
const wb = XLSX.read(f); // parse the array buffer
const ws = wb.Sheets[wb.SheetNames[0]]; // get the first worksheet
const opts = {
header: `<table id="excel-table">` ,
footer: `</table>`
};
const tableHTML = XLSX.utils.sheet_to_html(ws, opts); // generate HTML
this.getView().getModel().setProperty("/tableHTML", tableHTML); // update state
},
/* get live table and export the XLSX */
onExport: function () {
const tableHTML = this.getView().getModel().getProperty("/tableHTML"); // get HTML string from the model
const div = document.createElement("div"); // create temporary div to parse HTML
div.innerHTML = tableHTML; // insert HTML into div
const table = div.getElementsByTagName("table")[1]; // get inner table (bypasses outer wrapper)
const wb = XLSX.utils.table_to_book(table); // convert table element to workbook
XLSX.writeFileXLSX(wb, "SheetJSOpenUI5HTML.xlsx");
},
});
}
);
```
< details open >
< summary > < b > How to run the example< / b > (click to hide)< / summary >
:::note Tested Deployments
This demo was tested in the following environments:
| OpenUI5 | generator-easy-ui5 | Date |
|:--------|---------|---------|
2025-01-07 16:45:50 +00:00
| `1.131.1` | `3.8.1` | 2025-01-07 |
2024-12-26 16:51:25 +00:00
:::
1) Create a new site:
```bash
2025-01-07 16:45:50 +00:00
npm i --global generator-easy-ui5
2024-12-26 16:51:25 +00:00
npx yo easy-ui5 app
```
:::note Use the provided defaults:
- Application id: `sheetjs.openui5`
- Framework: `OpenUI5`
- Version: `1.131.1`
- Author: `SheetJS`
- Create new directory: `Y`
- Initialize git: `N`
:::
2) Install the dependencies and start server:
```bash
cd sheetjs.openui5
npm install
npm start
````
3) Open a web browser and access the displayed URL (`http://localhost:8080`)
4) Add SheetJS to your project by including this script tag in `webapp/index.html` :
< CodeBlock language = "html" value = "html" title = "webapp/index.html" >
{`< script src = "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js" > < / script > `}
< / CodeBlock >
2025-01-07 16:45:50 +00:00
5) Replace `webapp/view/Main.view.xml` with the complete [implementation above ](#view-implementation-html ).
6) Replace `webapp/controller/Main.controller.js` with the complete [implementation above ](#controller-implementation-html ).
2024-12-26 16:51:25 +00:00
The page will refresh and show a table with an Export button. Click the button and the page will
attempt to download `SheetJSOpenUI5HTML.xlsx` .
7) Build the site:
```bash
npm run build
```
The generated site will be placed in the `dist` folder.
8) Start a local web server:
```bash
npm run start:dist
```
Access the displayed URL (typically http://localhost:8080) with a web browser and test the page.
When the page loads, the app will fetch https://docs.sheetjs.com/pres.xlsx and
display the data from the first worksheet in a TABLE. The "Export XLSX" button
will generate a workbook that can be opened in a spreadsheet editor.
< / details >
2025-01-06 02:51:20 +00:00
[^1]: See ["ECMAScript Support" ](https://sdk.openui5.org/topic/0cb44d7a147640a0890cefa5fd7c7f8e.html#loio0cb44d7a147640a0890cefa5fd7c7f8e/section_UI5Mod ) for more details about OpenUI5 compatibility.
[^2]: See [`JSONModel` ](https://sdk.openui5.org/1.38.62/docs/api/symbols/sap.ui.model.json.JSONModel.html ) in the OpenUI5 documentation.
[^3]: See OpenUI5's [MVC Documentation ](https://sdk.openui5.org/topic/91f233476f4d1014b6dd926db0e91070 ) for detailed explanation of the pattern implementation.
[^4]: See ["Merged Cells" in "SheetJS Data Model" ](/docs/csf/features/merges ) for more details.
2025-01-15 18:43:08 +00:00
[^5]: See [`core:HTML` ](https://sdk.openui5.org/1.38.62/docs/api/symbols/sap.ui.core.HTML.html ) in the OpenUI5 documentation.
[^6]: See ["SheetJS Data Model" ](/docs/csf/ )
