--- title: Oracle Cloud Services pagination_prev: demos/local/index pagination_next: demos/extensions/index --- import current from '/version.js'; import CodeBlock from '@theme/CodeBlock'; [Oracle Cloud Services](https://www.oracle.com/cloud/) (OCI) is a cloud services platform which includes traditional virtual machine support, "Serverless Functions" and cloud storage. [SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing data from spreadsheets. This demo demonstrates how to integrate SheetJS with Oracle `Visual Builder Studio (VBS)`[^2] to build a web application that handles Excel files. You'll learn to create an application that can import spreadsheet data, store it in `Business Objects`[^1], display it in a table, and export it back to Excel format. :::caution pass Oracle Cloud Services iterates quickly and there is no guarantee that the referenced services will be available in the future. ::: :::note Tested Deployments This demo was last tested on 2025-02-04. ::: ## Visual Applications Oracle Cloud Services offers Visual Builder Studio a browser-based development environment for creating web applications with drag-and-drop components. ## Installation SheetJS libraries conform to the Oracle Cloud Visual Builder Studio (VBS) ECMAScript[^5] requirements. SheetJS libraries can be loaded in Oracle VBS site at different points in the app lifecycle. #### Configure in app-flow.json The `app-flow.json` method is recommended as it aligns better with Visual Builder Studio's module management system. 1. Click 📄 `Source` from the left sidebar 2. Open `webApps/sheetjs_demo_app/app-flow.json` 3. Add the following configuration after line 5: {`\ "requirejs": { "paths": { "xlsx": "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js" } } `} #### HTML {#installation-html} Oracle Cloud VBS is typically loaded in `SCRIPT` tag in `webApps/sheetjs_demo_app/index.html`. Similarly, [SheetJS Standalone scripts](/docs/getting-started/installation/standalone) 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"](/docs/api/) section of the documentation. ## Internal State The various SheetJS APIs work with various data shapes. The preferred state depends on the application. ### Business Objects `Business Objects`[^1] 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](https://docs.sheetjs.com/pres.xlsx) has one header row with "Name" and "Index" columns. In Oracle VBS, we model this as a Business Object with corresponding fields:
SpreadsheetBusiness Object Definition
![`pres.xlsx` data](pathname:///pres.png) ```json { "items" : [ { "name": "Pres", "fields": { "name": { "type": "string", "label": "Name" }, "index1": { "type": "number", "label": "Index" } } }] } ```
Here is how the data is represented when queried from the Business Object via REST call: ```json { "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`](/docs/api/parse-options) method parses the data into a workbook object. After selecting a worksheet, [`sheet_to_json`](/docs/api/utilities/array#array-output) generates row objects that can be created as Business Object records using the auto-generated REST API. Here is a sample flow diagram and method for downloading a workbook, generating rows from the first worksheet, and updating a `Business Object`[^1]: ```mermaid flowchart LR xlsx[(Remote\nFile)] bo1[(Data\nArrayBuffer)] wb(SheetJS\nWorkbook) ws(SheetJS\nWorksheet) json(JSON\nData) bo2[(Business\nObject)] xlsx --> |fetch\n\n| bo1 bo1 --> |XLSX.read\n\n| wb wb --> |wb.Sheets\nselect| ws ws --> |sheet_to_json\n\n| json json --> |REST API\ncreate| bo2 linkStyle 1,2,3 color:blue,stroke:blue; ``` {` define(['vb/action/actionChain', 'vb/action/actions', 'xlsx'], (ActionChain, Actions, XLSX) => { class ButtonActionChain extends ActionChain { async run(context) { // fetch XLSX file const data = await (await fetch("https://docs.sheetjs.com/pres.xlsx")).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) }; // 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-table` supports direct binding to Business Objects for data display. The view structure defines both the data source binding and column layout: The following example uses the `Table`[^4] component to display data. {`\
// highlight-start // highlight-end
`}
#### Exporting Data 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: ```mermaid flowchart LR bo[(Business\nObject)] rest(REST API\nCall) json(JSON\nArray) ws(SheetJS\nWorksheet) wb(SheetJS\nWorkbook) xlsx[(XLSX\nFile)] bo --> |getall_Pres\nendpoint| rest rest --> |transform\nresponse| json json --> |json_to_sheet\n\n| ws ws --> |book_new\n\n| wb wb --> |writeFileXLSX\n\n| xlsx linkStyle 2,3,4 color:blue,stroke:blue; ``` {` 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; }); `} :::note pass Visual Builder Studio provides a visual development environment and handles the build and deployment process automatically. ::: ## Importing Data {#importing-data-snippet} The import functionality enables data transfer from an Excel spreadsheet into your Oracle VBS application. The process begins by fetching the XLSX file, parsing it using SheetJS, and then creating corresponding Business Object records. ```javascript title="" 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 {#exporting-data-snippet} 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. ```javascript 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; }); ``` ## Oracle Visual Builder Studio Web Applications Demo :::note pass At the time of writing, Oracle Cloud offers a 30-day free trial that includes Visual Builder Studio access. ::: 0. If you do not have an account create a new Oracle Cloud free tier account[^3]. ### Visual Builder Setup 1. Sign in to the [Oracle Cloud Management Console](https://cloud.oracle.com/) with your created account. 2. Type "Visual Builder Studio" in the top search box and click Visual Builder Studio (under services). ![Oracle Cloud search for "Visual Builder Studio"](pathname:///oraclecloud/search_box_visual_builder.png) 3. Before creating Visual Builder Studio Instances we need to create an instance. Click `Visual Builder` from the left sidebar and click Create an instance. ![Create Visual Builder Instance](pathname:///oraclecloud/create_vb_instance.png) - Give it a name: `sheetjs-demo-vb-instance` - Select network access: `Default (No access rules.)` - Nodes: `1` 4. Now click `Visual Builder Studio` from the left sidebar and click `Create Visual Builder Studio` and give it instance name: `sheetjs-vbs-instance` and click next and set select compartment to `yourusername (root)`. Lastly, click `Create Visual Builder Studio` (this will take 5-15 minutes to fully setup). - Click link name `sheetjs-vbs-instance` 5. Click `Service Console` create a new project and fill it with the following inputs. - Project Details: `sheetjs-demo-project` - Project Template: `Empty Project` - Project Properties: `Markdown` - Click Finish 6. Select `Project Home` from the left sidebar and create an environment. - Environment Name: `sheetjs-demo-env` - Click Create - Click `Add Instance` ![Connect instance to environment](pathname:///oraclecloud/env_connect_to_instance.png) 7. In Environments select the Service Instances tab and search for `Instance URL` if not shown click details to expand Visual Builder `sheetjs-demo-vb-instance` and open `Instance URL` This will open Visual Builder Studio. 8. Click `New Application` and set - Application Display Name: `sheetjs-vbs-demo` - Application Template: `Empty Application` - Click Finish 9. Create a new Business Object by clicking **Business Object** card in the Welcome tab or from the sidebar as shown ![Create a new Business Object](pathname:///oraclecloud/create_business_object.png) - Name: `Pres` - Display: `President` 10. Click `Pres` Business Object and select Fields tab. Then, create a new field by clicking the `+Fields` button and select first drop-down `Field`. - Label1: `Name` - Type1: Click `A` (`String`) - Label2: `Index` - Type2: Click `#` (`Number`) ![Add two new fields](pathname:///oraclecloud/creating_new_fields_name_index.png) 11. Click 🖥️ Web Applications from the left sidebar and create a new Web Application by clicking `+Web Application` You should have the following fields. - Application Name: `sheetjs_demo_app` - Navigation Style: `None` - Click Create 12. [Adding SheetJS Module](#installation) to the App Click 📄 `Source` from the left sidebar and paste the following on `webApps/sheetjs_demo_app/app-flow.json` {`\ "requirejs": { "paths": { "xlsx": "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js" } } `} ![Adding Sheetjs to the web application](pathname:///oraclecloud/adding_sheetjs_to_app.png) 13. Let's create the UI for our application we will be creating a table and two buttons one for import XLSX and one for export XLSX. - From the left sidebar click the 🖥️ `Web Applications` and select `main-start` - Select Page Designer and drag and drop two `Button` components and one `Table` Component to the canvas ![Darg and drop ui components to canvas](pathname:///oraclecloud/drag_drop_components_to_canvas.png) 14. Creating our button event handler - Now select the left button in the canvas and on the right side on `General` tab set ID to `import-xslx` and label to `Import XLSX`. - Now select the `Events` tab and click `+ Event Listener` drop down button and select `On 'ojAction'` - Now it should auto-select `Action Chains` if not click from top tab option. - Switch from `Design` to `Code` from top right ![Switch from Design to Code in Action Chains for the button](pathname:///oraclecloud/action_chain_select_code.png) 15. Replace `Action Chains > ButtonActionChain > Code` with the importing data snippet in the ["Importing Data"](#importing-data-snippet) example code. 16. Now repeat step 14 for the second button - Now select the first button in the canvas and on the right side on `General` tab set ID to `export-xslx` and label to `Export XLSX`. - Now select the `Events` tab and click `+ Event Listener` drop down button and select `On 'ojAction'` - Now it should auto-select `Action Chains` if not click from top tab option. - Switch from `Design` to `Code` from top right 17. Replace `Action Chains > ButtonActionChain1 > Code` with the exporting data snippet in the ["Exporting Data"](#exporting-data-snippet) example code. 18. Connect the Business Object `Pres` to the table. - Now select `Page Designer` and in the canvas select the table component from the right sidebar select `Quick Start` and then `Add Data` - This opens up a modal on `Choose the source of your data` select `Pres` Business Object and click next. ![Connecting Business Object Pres to the table](pathname:///oraclecloud/connecting_business_object.png) - On Bind Data step 2 from the left sidebar named `Endpoint Structure` check box `name` and `index1` then click next and lastly click finish. ![Bind columns to field name and index1](pathname:///oraclecloud/bind_columns_to_fields_name_index1.png) 19. Testing the Application - a) Launch the Preview: - Look for the Play (▶️) icon in the top-right corner of the Visual Builder Studio - Click it to open your application in a new browser tab - b) Test the Import Function: - In the preview tab, click the "Import XLSX" button - Navigate back to Visual Builder Studio - Select the `Pres` business object - Click the "Data" tab - Verify that new records have been created with the president names and index - Return to your application preview tab - Refresh the page - You should now see the table populated with the imported president data - c) Test the Export Function: - Click the "Export XLSX" button - This will trigger an automatic download of a file named "SheetJSOracleVisualBuilderAoO.xlsx" - Open the downloaded file using a spreadsheet editor. - Verify that the exported data matches what was displayed in your application's table [^1]: See Oracle VBS working with [Business Objects](https://docs.oracle.com/en/cloud/paas/visual-builder/visualbuilder-building-applications/working-business-objects1.html) for more detail. [^2]: [Oracle Visual Builder Studio](https://docs.oracle.com/en/cloud/paas/visual-builder/) [^3]: Registering for a free account [on the Oracle Cloud Free Tier](https://www.oracle.com/cloud/free/) requires a valid phone number and a valid credit card. [^4]: See [Oracle VBS Table Component](https://docs.oracle.com/en/middleware/developer-tools/jet/13/reference-api/oj.ojTable.html) for more details. [^5]: See ["JavaScript Support in Oracle VBS"](https://docs.oracle.com/en/cloud/paas/visual-builder/visualbuilder-building-applications/work-javascript-editor1.html?utm_source=chatgpt.com) for more details on custom JavaScript functionality and module handling.