sheetjs/docs.sheetjs.com
1
Fork 4
Code Issues 1 Pull Requests 1 Projects Releases Wiki Activity
d3e0baa6bb
docs.sheetjs.com/docz/docs/03-demos/02-frontend/10-openui5.md
SheetJS d3e0baa6bb error notes
2025-02-10 02:13:57 -05:00

21 KiB
Raw Blame History

title sidebar_label description pagination_prev pagination_next sidebar_position
Sheets in UI5 Sites OpenUI5 / SAPUI5 Build enterprise-grade applications with OpenUI5. Seamlessly integrate spreadsheets into your app using SheetJS. Bring Excel-powered workflows and data to the modern web. demos/index demos/grid/index 10

import current from '/version.js'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock';

OpenUI5 is a JavaScript framework for building enterprise-ready web applications. It is compatible with the SAPUI5 framework.

SheetJS is a JavaScript library for reading and writing data from spreadsheets.

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.

:::info pass

Docs Issue #20 includes a complete example starting from the OpenUI5 "Worklist App Tutorial".

:::

Installation

SheetJS libraries conform to the UI5 ECMAScript requirements1. SheetJS libraries can be loaded in a UI5 site at different points in the app lifecycle.

UI5 Module

The SheetJS Standalone scripts 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 script webapp/index.js can load the ./xlsx.full.min dependency:

sap.ui.define([
  // highlight-next-line
  "./xlsx.full.min", // relative path to script, without the file extension
  /* ... other libraries ... */
], function (
  // 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
});

:::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.

:::

HTML

UI5 is typically loaded in a SCRIPT tag in webapp/index.html. Similarly, SheetJS Standalone scripts can be loaded with a SCRIPT tag in the same HTML page:

{`\

`}

This will expose the XLSX global object, which includes the functions listed in the "API Reference" section of the documentation.

:::caution pass

The SheetJS Standalone script must be loaded before the UI5 bootstrap script:

{`\

<head> </head> `}

:::

Internal State

The various SheetJS APIs work with various data shapes. The preferred state depends on the application.

JSON Model

The UI5 JSONModel2 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.

State

The example presidents sheet has one header row with "Name" and "Index" columns. The natural JS representation is an object for each row, where the keys are specified in the first row:

SpreadsheetState

pres.xlsx data

 
[
  { 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 }
]

Here is a basic example of initializing a model. A more complete implementation will be shown later.

sap.ui.define(["sap/ui/model/json/JSONModel"], function (JSONModel) {
  // highlight-next-line
  const oModel = new JSONModel({ presidents: [] });
});

Updating State

Starting from a spreadsheet file, the SheetJS read method parses the data into a SheetJS workbook object3. After selecting a worksheet, the sheet_to_json method generates row objects that can be assigned to the model.

Here is a sample flow diagram and method for downloading a workbook, generating rows from the first worksheet, and updating a UI5 JSONModel:

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
  linkStyle 1,2,3 color:blue,stroke:blue;

_loadExcelFile: async function () {
  /* Download from https://docs.sheetjs.com/pres.xlsx */
  const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer();

  // 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 */
  this.getView().getModel().setProperty("/presidents", data);
  // highlight-end
}

Rendering Data

In UI5, the "Model-View-Controller"4 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.

The following example uses the Table component5 to display data.

<mvc:View>
  <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>
</mvc:View>

Exporting Data

The getProperty method6 of the JSONModel pulls data from the UI5 model. If an array of objects was pushed with setProperty, the getProperty method will return an array of objects.

The SheetJS json_to_sheet function will create a SheetJS worksheet object7 from the data in the array. The book_new method will create a SheetJS workbook object that includes the new worksheet. writeFile will attempt to generate a file and initiate a download.

flowchart LR
  state((State\nJSONModel))
  aoo[(Array of\nObjects)]
  ws(SheetJS\nWorksheet)
  wb(((SheetJS\nWorkbook)))
  file[(XLSX\nexport)]
  state --> |getProperty\n\n| aoo
  aoo --> |json_to_sheet\n\n| ws
  ws --> |book_new\n\n| wb
  wb --> |writeFile\n\n| file
  linkStyle 1,2,3 color:blue,stroke:blue;

Here is a sample method for exporting data from the UI5 JSONModel to XLSX:

/* get model data and export to XLSX */
onExport: function () {
  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(ws, "Data");
  /* export to XLSX */
  XLSX.writeFileXLSX(wb, "SheetJSOpenUI5AoO.xlsx");
}

This method can be bound to the press event of a sap.m.Button control:

<mvc:View>
  <Page>
    <!-- The `onExport` method is bound to the `press` event -->
    <Button text="Export Data" press=".onExport" />
  </Page>
</mvc:View>

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:

View Implementation
<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="Index" /></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>
Controller Implementation
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 */
        this._loadExcelFile();
      },

      _loadExcelFile: async function () {
        /* fetch and parse file */
        const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer();
        const wb = XLSX.read(f);
        /* extract data from first worksheet */
        const ws = wb.Sheets[wb.SheetNames[0]];
        const data = XLSX.utils.sheet_to_json(ws);
        /* update state model */
        this.getView().getModel().setProperty("/presidents", data);
      },

      onExport: function () {
        /* fetch data from model */
        const data = this.getView().getModel().getProperty("/presidents");
        /* generate workbook */
        const ws = XLSX.utils.json_to_sheet(data);
        const wb = XLSX.utils.book_new(ws, "Data");
        /* export to XLSX */
        XLSX.writeFileXLSX(wb, "SheetJSOpenUI5AoO.xlsx");
      },
    });
  }
);
How to run the example (click to hide)

:::note Tested Deployments

This demo was tested in the following environments:

OpenUI5 Date
1.132.1 2025-01-24

:::

  1. Create a new site:
npm i --global generator-easy-ui5
npx yo easy-ui5 app

When prompted, enter the following options:

  • Enter your application id (namespace)?: Type sheetjs.openui5 and press Enter
  • Which framework do you want to use?: Press Enter (OpenUI5 should be the default)
  • Which framework version do you want to use?: Type 1.132.1 and press Enter
  • Who is the author of the application?: Press Enter (use the default author)
  • Would you like to create a new directory for the application?: Type Y and press Enter
  • Would you like to initialize a local git repository for the application?: Type N and press Enter

Expected output

  1. Install the dependencies and start server:
cd sheetjs.openui5
npm install
npm start
  1. Open a web browser and access the displayed URL (http://localhost:8080).

In the file listing, click index.html to launch the app.

  1. Add the SheetJS Standalone script to webapp/index.html after the title tag:

{\ <title>UI5 Application: sheetjs.openui5</title> <!-- highlight-next-line --> <script src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>}

  1. Replace webapp/view/Main.view.xml with the Main.view.xml snippet in the "View Implementation" section.

  2. Replace webapp/controller/Main.controller.js with the Main.controller.js example in the "Controller Implementation" section.

  3. Switch back to the browser window.

The page will refresh and show a table with an Export button.

Click the button and the page will attempt to download SheetJSOpenUI5AoO.xlsx. This file can be inspected with a spreadsheet editor.

  1. Build the site:
npm run build:opt

The generated site will be placed in the dist folder.

:::caution pass

SAP recommends npm run build. This does not generate a proper standalone site! Sites built with npm run build must be served with npm run start:dist.

This demo uses the build:opt target to ensure that a proper static site is generated. The dist folder in this demo can be deployed on a static host.

:::

  1. Start a local web server:
npx http-server 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.

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. However, this does not handle merge cells8 well!

The sheet_to_html function generates HTML that is aware of merges and other worksheet features.

To render the HTML string from the model, the property from the model should be bound to the content property of a UI5 core:HTML9 control.

On export, the table_to_book method creates a SheetJS workbook object from the rendered HTML table.

View Implementation
<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 id="tbl" content="{/tableHTML}" />
      <Button text="Export XLSX" press=".onExport"/>
    </content>
  </Page>
</mvc:View>
Controller Implementation
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 */
        this._loadExcelFile();
      },

      _loadExcelFile: async function () {
        /* fetch and parse file */
        const f = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).arrayBuffer();
        const wb = XLSX.read(f);
        /* generate HTML table from first worksheet */
        const ws = wb.Sheets[wb.SheetNames[0]];
        const opts = { header: `<table>`, footer: `</table>` };
        const tableHTML = XLSX.utils.sheet_to_html(ws, opts);
        /* update state model */
        this.getView().getModel().setProperty("/tableHTML", tableHTML);
      },

      onExport: function () {
        /* Get reference to the `TABLE` element in the model */
        const table = this.getView().byId("tbl").getDomRef();

        /* Generate workbook */
        const wb = XLSX.utils.table_to_book(table);

        /* Export to XLSX */
        XLSX.writeFileXLSX(wb, "SheetJSOpenUI5HTML.xlsx");
      },
    });
  }
);
How to run the example (click to hide)

:::note Tested Deployments

This demo was tested in the following environments:

OpenUI5 Date
1.132.1 2025-01-24

:::

  1. Create a new site:
npm i --global generator-easy-ui5
npx yo easy-ui5 app

When prompted, enter the following options:

  • Enter your application id (namespace)?: Type sheetjs.openui5 and press Enter
  • Which framework do you want to use?: Press Enter (OpenUI5 should be the default)
  • Which framework version do you want to use?: Type 1.132.1 and press Enter
  • Who is the author of the application?: Press Enter (use the default author)
  • Would you like to create a new directory for the application?: Type Y and press Enter
  • Would you like to initialize a local git repository for the application?: Type N and press Enter

Expected output

  1. Install the dependencies and start server:
cd sheetjs.openui5
npm install
npm start
  1. Open a web browser and access the displayed URL (http://localhost:8080)

In the file listing, click index.html to launch the app.

  1. Add the SheetJS Standalone script to webapp/index.html after the title tag:

{\ <title>UI5 Application: sheetjs.openui5</title> <!-- highlight-next-line --> <script src="https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"></script>}

  1. Replace webapp/view/Main.view.xml with the Main.view.xml snippet in the "View Implementation" section.

  2. Replace webapp/controller/Main.controller.js with the Main.controller.js example in "Controller Implementation".

  3. Switch back to the browser window.

The page will refresh and show a table with an Export button.

Click the button and the page will attempt to download SheetJSOpenUI5HTML.xlsx. This file can be inspected with a spreadsheet editor.

  1. Build the site:
npm run build:opt

The generated site will be placed in the dist folder.

:::caution pass

SAP recommends npm run build. This does not generate a proper standalone site! Sites built with npm run build must be served with npm run start:dist.

This demo uses the build:opt target to ensure that a proper static site is generated. The dist folder in this demo can be deployed on a static host.

:::

  1. Start a local web server:
npx http-server 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.

  1. See "ECMAScript Support" for more details about OpenUI5 compatibility. ↩︎

  2. See JSONModel in the OpenUI5 documentation. ↩︎

  3. See "SheetJS Data Model" ↩︎

  4. See OpenUI5's MVC Documentation for detailed explanation of the pattern implementation. ↩︎

  5. See "List, List Item, and Table" in the OpenUI5 documentation. ↩︎

  6. See getProperty of class sap.ui.model.json.JSONModel in the OpenUI5 documentation. ↩︎

  7. See "Worksheet Object" in "SheetJS Data Model" for more details. ↩︎

  8. See "Merged Cells" in "SheetJS Data Model" for more details. ↩︎

  9. See core:HTML in the OpenUI5 documentation. ↩︎