add Oracle Cloud Visual Builder Studio demo guide.

docz/docs/03-demos/30-cloud/03-oraclecloud.md

@@ -0,0 +1,541 @@
+---
+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:
+
+<CodeBlock language="json" value="json">{`\
+"requirejs": {
+    "paths": {
+      "xlsx": "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"
+    }
+ }
+`}
+</CodeBlock>
+
+#### 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:
+
+<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.
+
+
+## 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:
+
+<table>
+  <thead><tr><th>Spreadsheet</th><th>Business Object Definition</th></tr></thead>
+  <tbody><tr><td>
+
+![`pres.xlsx` data](pathname:///pres.png)
+
+</td><td>
+
+```json
+{
+  "items" : [ {
+    "name": "Pres",
+    "fields": {
+      "name": {
+        "type": "string",
+        "label": "Name"
+      },
+      "index1": {
+        "type": "number",
+        "label": "Index"
+      }
+    }
+  }]
+}
+```
+
+</td></tr></tbody></table>
+
+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;
+```
+
+<CodeBlock language="javascript" value="javascript" title="Download workbook, extract data from first worksheet, and update ">{`
+  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;
+  });
+`}
+</CodeBlock>
+
+#### 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.
+
+<CodeBlock language="html" value="html" title="Example View for displaying an array of objects [sheetjs_demo_app/main/main-start]">{`\
+<div class="oj-flex">
+  // highlight-start
+  <!-- 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>
+  // highlight-end
+</div>
+`}
+</CodeBlock>
+
+
+#### 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;
+```
+
+<CodeBlock language="javascript" value="javascript" title="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;
+  });
+`}
+</CodeBlock>
+
+:::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`
+
+<CodeBlock language="json" value="json" title="copy paste after line 5">{`\
+"requirejs": {
+    "paths": {
+      "xlsx": "https://cdn.sheetjs.com/xlsx-${current}/package/dist/xlsx.full.min.js"
+    }
+ }
+`}
+</CodeBlock>
+
+![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.