Skip to main content

Oracle Cloud Infrastructure

Oracle Cloud Infrastructure (OCI) is a cloud services platform for building and deploying line of business applications.

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

This demo explores the "Visual Builder Studio" (VBS) environment1. We'll use VBS and SheetJS to build a web application that handles Excel files.

In the "Complete Example", we'll create an application that imports data from spreadsheet, stores data in "Business Objects"2, displays data in table components, and exports Business Objects to new spreadsheets.

Oracle Cloud Infrastructure iterates quickly and there is no guarantee that the referenced services will be available in the future.

Tested Deployments

This demo was last tested on 2025-02-04.

Visual Applications​

"Visual Builder Studio", a core Oracle Cloud Infrastructure offering, is a browser-based development environment for creating web applications with drag-and-drop components.

Installation​

SheetJS libraries conform to Visual Builder Studio ECMAScript3 requirements. They can be loaded in VBS applications at different points in the app lifecycle.

RequireJS Module​

The SheetJS Standalone scripts comply with AMD define semantics. They support define out of the box.

Module Alias

Unlike other platforms, Oracle Visual Builder define requires module aliases. Aliases are stored in app-flow.json. SheetJS scripts are designed to use the xlsx alias.

An alias can be added in Visual Builder Studio with the following steps:

  1. Click 📄 Source from the left sidebar.
  2. Expand the webApps folder.
  3. Expand the subfolder whose name matches the "Application Name" for the site.
  4. Open app-flow.json within the folder from step 3.
  5. Add the following lines after line 5:
app-flow.json (add after line 5)
  "requirejs": {
    "paths": {
      "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min"
    }
  },

Script Reference

After defining the alias, action chains can load the module using define:

Action Chain Code (loading the SheetJS dependency)
define([
  "xlsx",
  /* ... other libraries ... */
  'vb/action/actionChain', 'vb/action/actions'
], (
  XLSX,
  /* ... variables for the other libraries ... */
  ActionChain, Actions
) => {
  class MyActionChain extends ActionChain {
    async run(context) {
      console.log(XLSX.version); // use XLSX in the callback
    }
    /* ... other methods ... */
  }
  return MyActionChain;
});

HTML​

SheetJS Standalone scripts can be loaded with a SCRIPT tag in the index.html entry page for the app. Typically this file is stored in the app folder.

For example, if the app is named sheetjs_demo_app, the entrypoint HTML file is webApps/sheetjs_demo_app/index.html.

The script should be added in the HEAD block:

index.html (add in the HEAD block)
<script src="https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min.js"></script>

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

The Visual Builder scripts are injected at <!-- visualBuilderScripts -->. This comment is typically in the BODY block:

index.html (base template)
<body class="oj-web-applayout-body vb-web-applayout-body">

  <oj-vb-content config="[[vbApplication]]"></oj-vb-content>

  <!-- visualBuilderScripts -->

Adding the SheetJS Standalone script to the HEAD block ensures the script will be processed before loading Oracle Visual Builder scripts.

Business Objects​

"Business Objects"2 in Oracle VBS provides a server-side model implementation for persistent data storage.

Think of them as a combination of a data model and database table that handles both data storage and UI binding.

Business Object Definition​

The example presidents sheet has a header row with "Name" and "Index" columns. In Oracle VBS, we model this as a Business Object with two fields.

Schema​

Fields in Business Objects must have a specified type. A sample business object definition for the following schema is shown below:

Field IDTypeField Label
namestringName
index1numberIndex
Sample Business Object Definition
{ "items" : [ {
    "name": "Pres",
    "fields": {
      "name": { "type": "string", "label": "Name" },
      "index1": { "type": "number", "label": "Index" }
    }
} ] }

Data​

Actions can query data from the Business Object with REST calls. The items property of the response is an array of objects.

Fields are identified by Field ID. The field names do not appear in the result.

SpreadsheetQuery Result

pres.xlsx data

{
  "items": [
    { "name": "Bill Clinton", "index1": 42 },
    { "name": "GeorgeW Bush", "index1": 43 },
    { "name": "Barack Obama", "index1": 44 },
    { "name": "Donald Trump", "index1": 45 },
    { "name": "Joseph Biden", "index1": 46 }
  ]
}

Updating Business Object​

Starting from a spreadsheet file, the SheetJS read method parses the data into a workbook object. After selecting a worksheet, sheet_to_json generates row objects. Using the auto-generated REST API, new Business Object records can be created.

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

Download workbook, extract data from first worksheet, and upload
  define(['vb/action/actionChain', 'vb/action/actions', 'xlsx'], (ActionChain, Actions, XLSX) => {
    class ButtonActionChain extends ActionChain {
      async run(context) {
        /* fetch spreadsheet file */
        const url = "https://docs.sheetjs.com/pres.xlsx";
        const data = await (await fetch(url)).arrayBuffer();

        /* parse */
        const wb = XLSX.read(data);
        /* convert the first worksheet to json */
        const ws = wb.Sheets[wb.SheetNames[0]];
        const jsonData = XLSX.utils.sheet_to_json(ws);

        for (const row of jsonData) { // loop over data rows
          /* create object that follows business object definition */
          const presData = {
            name: row.Name,
            index1: Number(row.Index)
          };

          /* update business object with new record */
          await Actions.callRest(context, {
            endpoint: 'businessObjects/create_Pres',
            body: presData
          });
        }
      }
    }
    return ButtonActionChain;
  });

Rendering Data​

In Oracle VBS, the table component oj-table4 supports direct binding to Business Objects for data display. The view structure specifies the data source binding and column layout.

When using the design mode to add a Table, VBS will use a ServiceDataProvider with columns based on the specified Endpoint Structure. The following view code was generated when testing the "Complete Example":

Example View for displaying an array of objects [sheetjs_demo_app/main/main-start]
<div class="oj-flex">
  <!-- Data source for the table -->
  <oj-table scroll-policy="loadMoreOnScroll" class="oj-flex-item oj-sm-12 oj-md-12"
    data="[[$variables.presListSDP]]"
    columns='[
      {"headerText":"Name","field":"name"},
      {"headerText":"Index","field":"index1"}
    ]'>
  </oj-table>
</div>

Exporting Business Objects​

The export functionality converts Business Object data into an Excel spreadsheet. The process involves retrieving data through REST API call, transforming it into a format suitable for SheetJS, and generating an XLSX file. Here's the complete flow:

Download workbook, extract data from the first worksheet, and update 
define(['vb/action/actionChain', 'vb/action/actions', 'xlsx'], (ActionChain, Actions, XLSX) => {
  class ButtonActionChain1 extends ActionChain {
    async run(context) {
      // get pres data
      const presDataResponse = await Actions.callRest(context, {
        endpoint: 'businessObjects/getall_Pres',
        parameters: {
          fields: 'name,index1'
        }
      });

      // transform to simple array
      const simplifiedData = presDataResponse.body.items.map(item => ({
        Name: item.name,
        Index: item.index1
      }));

      // generate workbook
      const ws = XLSX.utils.json_to_sheet(simplifiedData);
      const wb = XLSX.utils.book_new(ws, "Presidents");

      // export to XLSX which triggers a download
      XLSX.writeFileXLSX(wb, "SheetJSOracleVisualBuilderAoO.xlsx");
    }
  }
  return ButtonActionChain1;
});

Importing Data​

The import functionality enables data transfer from an Excel spreadsheet into the Oracle VBS application. The process begins by fetching the XLSX file, parsing it using SheetJS, and then creating corresponding Business Object records.

Importing Data code
define([
  'vb/action/actionChain',
  'vb/action/actions',
  'vb/action/actionUtils',
  'xlsx'
], (
  ActionChain,
  Actions,
  ActionUtils,
  XLSX
) => {
  'use strict';

  class ButtonActionChain extends ActionChain {

    /**
     * @param {Object} context
     */
    async run(context) {
      const { $page, $flow, $application, $constants, $variables } = context;

      // fetch XLSX file
      const url = "https://docs.sheetjs.com/pres.xlsx";
      const data = await (await fetch(url)).arrayBuffer();
      const wb = XLSX.read(data);

      // get the first worksheet
      const ws = wb.Sheets[wb.SheetNames[0]];

      // convert to json
      const jsonData = XLSX.utils.sheet_to_json(ws);

      // process each row and create business object records
      for (const row of jsonData) {
        const presData = {
          name: row.Name,
          index1: Number(row.Index)
        };

        // create a business object record
        await Actions.callRest(context, {
          endpoint: 'businessObjects/create_Pres',
          body: presData
        });
      }
    }
  }
  return ButtonActionChain;
});

Exporting Data​

The export functionality allows you to convert Business Object data into Excel spreadsheets. This process involves retrieving data from the Business Object using REST API calls, transforming it into a format suitable for SheetJS, and generating an XLSX file.

Exporting Data code
define([
  'vb/action/actionChain',
  'vb/action/actions',
  'vb/action/actionUtils',
  'xlsx'
], (
  ActionChain,
  Actions,
  ActionUtils,
  XLSX
) => {
  'use strict';

  class ButtonActionChain1 extends ActionChain {

    /**
     * @param {Object} context
     */
    async run(context) {
      const { $page, $flow, $application, $constants, $variables } = context;

      // get pres data
      const presDataResponse = await Actions.callRest(context, {
        endpoint: 'businessObjects/getall_Pres',
        parameters: {
          fields: 'name,index1'
        }
      });

      // transform to simple array
      const simplifiedData = presDataResponse.body.items.map(item => ({
        Name: item.name,
        Index: item.index1
      }));

      // generate workbook
      const ws = XLSX.utils.json_to_sheet(simplifiedData);
      const wb = XLSX.utils.book_new(ws, "Presidents");

      /* export to XLSX */
      XLSX.writeFileXLSX(wb, "SheetJSOracleVisualBuilderAoO.xlsx");

    }
  }
  return ButtonActionChain1;
});

Complete Example​

At the time of writing, Oracle Cloud offers a 30-day free trial that includes Visual Builder Studio access.

  1. If you do not have one, create a new Oracle Cloud free tier account5.

  2. Sign in to the Oracle Cloud Management Console.

Visual Builder Setup​

In this section, we will configure VBS and create a new instance.

  1. Type "Visual Builder Studio" in the top search box and click "Visual Builder Studio" in the "Services" section.

Oracle Cloud search for "Visual Builder Studio"

  1. Click Visual Builder in the left sidebar. In the "List scope" section, if no Compartment is selected, click the dropdown and select a Compartment.

"Visual Builder" create instance

  1. Click "Create Instance".

In the Create Instance panel, enter the following options:

  • Name: sheetjs-demo-vb-instance
  • Nodes: 1 (it cannot be changed in a Free account)
  • Choose network access: Default (No access rules.)

The panel should look like the following screenshot:

Create Visual Builder Instance

  1. Click "Create Visual Builder Instance". The panel will close.

The instances table will include a new row for sheetjs-demo-vb-instance. When the instance is ready, the status will change to "ACTIVE".

Instance is ready

  1. Click "Visual Builder Studio" in the left sidebar.

  2. Click "Create Visual Builder Studio" in the main area.

In the Create Visual Builder Studio Instance panel, type sheetjs-vbs-instance in the Instance Name textbox and click "Next"

In the "CI/CD Setup" page, ensure "Yes, I authorize this" is checked. Select the compartment in the dropdown and click Create Visual Builder Studio.

You will be redirected to the instance page.

  1. Wait for the instance to be completed. The large circle will be green.

VBS Instance is ready

  1. Click Service Console. You will be redirected to the organization page.

  2. Scroll down and select the "Projects" tab. Click the "+ Create" button to create a new project. The "New Project" wizard has 4 steps:

  • In "Project Details", enter the Name sheetjs-demo-project and click "Next"

  • In "Project Template", select Empty Project and click "Next"

  • In "Project Properties" page, select Markdown and click "Next"

  • Click "Finish" (by default, the current user will be the "Project Owner")

You will be redirected to a provisioning page while resources are allocated:

Provisioning page

Once allocated, you will be redirected to the project page.

  1. Click "⌂ Project Home" in the left sidebar and click "+ Create Environment".

In the popup, type sheetjs-demo-env in the "Environment Name" text box and click "Create". You will be redirected to the Environments page.

  1. Click + Add Instance. In the modal, select the following:
  • Instance Type: "Visual Builder and Oracle Integration"
  • Add Instance Using: "Instance List"
  • Check the box in the sheetjs-demo-vb-instance table row.

The selections should match the following screenshot:

Connect instance to environment

After making the selections, click "Add". Once the instance is created, there will be a checkmark next to sheetjs-demo-env in the main area.

Instance created

  1. Select the "Service Instances" tab and find the sheetjs-demo-vb-instance card. If "Instance URL" is not shown, click "Details" to show the URL.

Environment card

Click the "Instance URL". Visual Builder will be launched in a new window.

  1. Click "+ New Application". In the popup, enter the following options:
  • Application Display Name: sheetjs-vbs-demo
  • Application Name: sheetjs_vbs_demo (automatic)
  • Application Template: Empty Application (default)

Click "Finish". After a short wait, the browser will redirect to the new app.

Business Object Setup​

In this section, we will create a new Business Object.

  1. Click the Business Objects card in the Welcome tab or the "⛁" icon in the left sidebar. The "Business Objects" panel will be displayed.

Create a new Business Object

Click "+ Business Object". In the popup, enter the following:

  • Name: Pres
  • Display Label: President

Click "Create". You will be redirected to the Business Object page.

  1. Select Pres in the Business Objects panel and select the "Fields" tab.

Business Object - Fields

  1. Click "+ Field" and select "Field" in the dropdown. In the displayed form, enter the following options:
  • Label: Name
  • Type: Click A (String will be displayed next to Type)

Click "Create Field".

  1. Click "+ Field" and select "Field" in the dropdown. In the displayed form, enter the following options: (we are creating a second field)
  • Label: Index
  • Type: Click # (Number will be displayed next to Type)

Click "Create Field".

  1. Scan the main table and verify that two new rows were added:

Add two new fields

Web App Creation​

In this section, we will create a new web application.

  1. Click "🖥️ Web Applications" in the left bar and click "+ Web Application". In the popup, enter the following options:
  • Application Name: sheetjs_demo_app
  • Navigation Style: None

Click "Create". You will be redirected to the page designer.

If prompted to share clipboard, select "Allow".

SheetJS Alias​

In this section, we will create an alias to the SheetJS standalone script hosted on the SheetJS CDN

  1. Click 📄 Source from the left sidebar.

  2. In the file tree, if app-flow.json is not visible, click the triangle next to sheetjs_demo_app to expand the folder.

Clicking on the sheetjs_demo_app name has no effect! You must click the triangle next to the label to expand the folder.

  1. Select app-flow.json within the sheetjs_demo_app folder.

A new code window will be displayed in the main area.

  1. Copy the following codeblock and insert it after line 5 in the code editor:
webApps/sheetjs_demo_app/app-flow.json (insert after line 5)
  "requirejs": {
      "paths": {
        "xlsx": "https://cdn.sheetjs.com/xlsx-0.20.3/package/dist/xlsx.full.min"
      }
  },

The following screenshot shows the result after inserting the code:

Adding Sheetjs to the web application

App Interface​

In this section, we will create the UI for the application. It will include two buttons for import/export and a table for displaying data.

  1. Click "🖥️ Web Applications" in the left sidebar.

  2. In the tree, if main-start is not visible, click the triangle next to main to expand the folder.

Clicking on the main name does not expand the tree! You must click the triangle next to the label to expand the subtree.

  1. Select main-start within the main section.

  2. Select the "Page Designer" tab and select the "Design" tab.

In the page designer, drag and drop two Button components and one Table Component to the canvas.

The "Table" component is in the "Collections" section. Do not add a "Dynamic Table"!

Drag and drop UI components to canvas

Actions Setup​

In this section, we will add event handlers for the import and export buttons.

  1. Select the first button in the canvas.

  2. In the right panel, select the "General" tab. Enter the following details:

  • ID: import-xlsx
  • Label: Import XLSX

Press Enter after typing the label. The canvas will refresh.

  1. Select the "Events" tab and click "+ Event Listener". In the dropdown, click 🔔 On 'ojAction'.

  2. Click "Action Chains" in the top bar (next to "Page Designer").

  3. Select "Code" in the top-right tab.

Switch from Design to Code in Action Chains for the button

The main area will show a code editor.

  1. Copy the "Importing Data code" example code and paste in the code editor.

  2. Click "Page Designer" to return to the page designer.

  3. Select the second button in the canvas (not the "Import XLSX" button!)

  4. In the right panel, select the "General" tab. Enter the following details:

  • ID: export-xlsx
  • Label: Import XLSX

Press Enter after typing the label. The canvas will refresh.

  1. Select the "Events" tab and click "+ Event Listener". In the dropdown, click 🔔 On 'ojAction'.

  2. Click "Action Chains" in the top bar (next to "Page Designer").

  3. Select "Code" in the top-right tab.

  4. Copy the "Exporting Data code" example code and paste in the code editor.

Data Binding​

In this section, we will connect the Pres Business object to the Table.

  1. Click "Page Designer" to return to the page designer.

  2. Select the Table component in the canvas.

  3. In the right panel, select the "Quick Start" tab and click "Add Data".

Connecting Business Object Pres to the table

  1. Complete the "Add Data" wizard:

  • In "Choose the source of your data", select "Pres" in the "Business Objects" section and click "Next".

  • In the next section ("Bind Data"), check the box next to name and the box next to index1. After confirming the page looks like the following screenshot, click "Next".

Bind columns to field name and index1

  • In the next section ("Define Query") click "Finish".

App Testing​

In this section, we will test import and export functionality.

  1. Click the Preview button (▶️ icon) in the top-right corner of the page.

The application will be launched in a new browser tab.

  1. Click "Import XLSX".

  2. Switch back to the Visual Builder window.

  3. Click the "⛁" icon in the left sidebar and click the "Pres" Business Object.

  4. Switch to the "Data" tab and verify that new data has been added.

In some test runs, no data was added.

Repeat the "SheetJS Alias" steps and confirm the alias exists.

If the alias is missing, add the alias and launch a new Preview window.

Expected data for Pres Business Object

  1. Switch back to the "Preview" window and refresh the page.

The preview will now show the data from the "Pres" Business Object.

Preview of Pres Business Object

  1. Click the "Export XLSX" button.

The app will attempt to download SheetJSOracleVisualBuilderAoO.xlsx

Save the file and open with a spreadsheet editor. Confirm the spreadsheet matches the data shown in the app.

Footnotes​

  1. See "Oracle Visual Builder Studio" in the Oracle Cloud documentation. ↩

  2. See "Work With Business Objects" in the Oracle Visual Build Studio documentation. ↩ ↩2 ↩3

  3. See "JavaScript Support in Oracle VBS" for more details on custom JavaScript functionality and module handling. ↩

  4. See Oracle VBS Table Component for more details. ↩

  5. Registering for a free account on the Oracle Cloud Free Tier requires a valid phone number and a valid credit card. ↩