Excel to JSON Converter (Offline) – Documentation

Overview

The Excel to JSON Converter is a Forge component for converting Excel (.xlsx) and CSV (.csv) files to JSON format entirely offline. It uses the SheetJS library internally and supports multiple sheets, optional headers, and CSV files. The component is fully client-side and requires no external dependencies.

Key Features

• Converts Excel and CSV files to JSON

• Supports multiple sheets in a workbook

• Optional header row handling (HasHeader = true/false)

• Offline operation using SheetJS

• Includes a helper action to check library availability

• Consistent JSON output format

• Easy to integrate in Reactive Web and Mobile applications

Module Setup

1. Included Script

   • xlsx.full.min.js (SheetJS Community Edition) is already included in the module’s Interface → Scripts.

   • Consumers are required to add a dependency on the module and ensure the script is loaded in their application.

2. Client Actions

   • ConvertExceltoJson(FileBinary, HasHeader) → JsonResult

   • CheckActionIsAvailable() → Boolean

Inputs & Outputs

1. ConvertExceltoJson

Inputs

• ExcelFile (Type: Binary) - The Excel or CSV file uploaded by the user
• HasHeader (Type: Boolean) - Set true if the first row contains headers

Outputs

• JSONString (Type: Text) - JSON representation of the spreadsheet

Behavior:

• HasHeader = true: JSON array of objects with field names from the header row

• HasHeader = false: JSON array of arrays with raw cell values

JSON Output Examples:

Example 1 – HasHeader = true

Excel Sheet1:

Output:

{
  "Sheet1": [
    {"Name":"John","Age":30},
    {"Name":"Anna","Age":25}
  ]
}

Example 2 – HasHeader = false

Same sheet, HasHeader = false:

{
  "Sheet1": [
    ["Name","Age"],
    ["John",30],
    ["Anna",25]
  ]
}

Example 3 – Multiple Sheets

Sheet1:

Sheet2:

Output:

{
  "Sheet1":[
    {"Name":"John","Age":30}
  ],
  "Sheet2":[
    {"Product":"Pen","Price":1.5}
  ]
}

Usage Instructions

1. Add the Component

   • Import the Forge module into your application.

2. Prepare File Input

   • Use an Upload Widget or any binary source to get FileBinary.

3. Call Conversion Action

   // Example usage in a Client Action
   ConvertExceltoJson(FileBinary, HasHeader)
   

4. Handle JSON Output

   • Output is returned as Text (JSON string).

   • You can parse it using JSON.parse(JsonResult) for further processing.

     

Supported File Types

Note: Other Excel formats like .xls are not supported in this version.

Tips & Best Practices

• Always set HasHeader correctly to avoid empty JSON output.

• Empty cells are returned as null.

• For large files, CE version may be slower; Pro version can handle streaming (optional).

• Multi-sheet workbooks are automatically handled; each sheet becomes a key in the JSON object.

• Test with simple Excel/CSV files first to verify output structure.

Limitations

• Only SheetJS Community Edition is included.

• Does not currently detect Pro version features.

• Very large Excel files (>50k rows) may be slower on client-side conversion.

• Only supports .xlsx and .csv files.

Change Log

v1.0

• Initial release

• Multi-sheet and CSV support

• Optional header row handling

• Offline, client-side operation

• JSON output consistent for all sheets