Merge pull request #678 from jmaister/column-types

Allow to define the cell types and formats.

Author: jmaister

.github/workflows/webpack.yml

@@ -16,12 +16,15 @@ jobs:
         node-version: [18.x]
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
 
     - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v1
+      uses: actions/setup-node@v3
       with:
         node-version: ${{ matrix.node-version }}
+        cache: 'yarn'
 
     - run: yarn install
 

README.md

@@ -14,15 +14,17 @@
 
  - As part of the new version 3.0.0+, there is support for _XLSX_. The drawback is that the library is 200+ KB.
 
- - If you only need _XLS_ or _CSV_, use _2.X.X_ versions.
-
  - Check My Blog Page for Testing :
       [JavaScript export to Excel](http://jordiburgos.com/post/2013/javascript-export-to-excel.html)
 
       [ExcellentExport.js update: JavaScript export to Excel and CSV](http://jordiburgos.com/post/2017/excellentexport-javascript-export-to-excel-csv.html)
 
 # Revision history:
 
+### 3.9.0
+
+* Cell types and formats!!! Now you can define the cell type and format. For example, you can define a cell as a date or a number. You can also define the format of the cell. For example, you can define a cell as a date with the format "dd/mm/yyyy" or a number with the format "#,##0.00".
+
 ### 3.8.1
 
 * Activate XLSX compression by default. The example of index.bigtable.html went from 18Mb to 3Mb.
@@ -241,6 +243,7 @@
             fixValue: function(value, row, column) {return fixedValue} // Function to fix values, receiving value, row num, column num
             fixArray: function(array) {return array} // Function to manipulate the whole data array
             rtl: Use Right-to-left characters, boolean (optional)
+            formats: [...] // Array of formats for each column. See formats below.
             ...
         },
         {
@@ -259,6 +262,47 @@ It transforms BR to line breaks and then strips all the HTML tags.
                     return strippedString;
                 }
 
+## Formats
+
+You can specify an array with the formats for a specific cell range (i.e. A1:A100, A1:D100, A1:H1, etc).
+
+Each element in the format array consists on:
+
+```json
+{
+    "range": "A1:A100", // Range of cells to apply the format, mandatory
+    "format": {
+        "type": "<cell_type>", // Type of format, mandatory
+        "pattern": "<pattern>" // Pattern, optional
+    }
+}
+```
+
+`format` can be used from one of the predefined types if you use TypeScript
+
+```typescript
+{
+    "range": "A1:A100",
+    "format": PredefinedFormat.INTEGER
+}
+```
+
+`cell_type` can be one of the followint:
+
+    's': String
+    'n': Number
+    'd': Date
+    'b': Boolean
+
+`pattern` is a string with the format pattern used in Excel. For example:
+
+    '0' // Integer
+    '0.00' // 2 decimals
+    'dd/mm/yyyy' // Date
+    'dd/mm/yyyy hh:mm:ss' // Date and time
+    '0.00%' // Percentage
+    '0.00e+00' // Scientific notation
+    '@' // Text
 
 # Notes
 

dist/excellentexport.d.ts

@@ -6,6 +6,7 @@
  * @url: https://github.com/jmaister/excellentexport
  *
  */
+import { FormatDefinition } from './format';
 declare global {
     interface Navigator {
         msSaveBlob?: (blob: any, defaultName?: string) => boolean;
@@ -30,9 +31,11 @@ export interface SheetOptions {
     fixValue?(value: any, row: number, column: number): any;
     fixArray?(array: any[][]): any[][];
     rtl?: boolean;
+    formats?: (FormatDefinition | null)[];
 }
 declare const ExcellentExport: {
     version: () => string;
+    formats: import("./format").CellFormats;
     excel: (anchor: (HTMLAnchorElement | string), table: HTMLTableElement, name: string) => boolean;
     csv: (anchor: (HTMLAnchorElement | string), table: HTMLTableElement, delimiter?: string, newLine?: string) => boolean;
     convert: (options: ConvertOptions, sheets: SheetOptions[]) => string | false;

dist/excellentexport.js

@@ -0,0 +1,29 @@
+export declare enum CellType {
+    TEXT = "s",
+    NUMBER = "n",
+    DATE = "d",
+    BOOLEAN = "b"
+}
+export declare enum CellPattern {
+    INTEGER = "0",
+    DECIMAL = "0.00",
+    DATE = "dd/mm/yyyy",
+    TIME = "hh:mm:ss",
+    DATETIME = "dd/mm/yyyy hh:mm:ss",
+    CURRENCY = "[$$-409]#,##0.00;[RED]-[$$-409]#,##0.00",
+    PERCENTAGE = "0.00%",
+    EXPONENT = "0.00E+00",
+    TEXT = "@"
+}
+export interface CellFormat {
+    type: CellType;
+    pattern?: CellPattern;
+}
+export interface CellFormats {
+    [key: string]: CellFormat;
+}
+export declare const PredefinedFormat: CellFormats;
+export interface FormatDefinition {
+    range: string;
+    format?: CellFormat;
+}

dist/format.d.ts

@@ -1,29 +1,30 @@
-export declare const b64toBlob: (b64Data: string, contentType: string, sliceSize?: number) => Blob;
-export declare const templates: {
-    excel: string;
-};
-/**
- * Convert a string to Base64.
- */
-export declare const base64: (s: string) => string;
-export declare const format: (s: string, context: any) => string;
-/**
- * Get element by ID.
- * @param {*} element
- */
-export declare const getTable: (element: (HTMLTableElement | string)) => HTMLTableElement;
-/**
- * Get element by ID.
- * @param {*} element
- */
-export declare const getAnchor: (element: (HTMLAnchorElement | string)) => HTMLAnchorElement;
-/**
- * Encode a value for CSV.
- * @param {*} value
- */
-export declare const fixCSVField: (value: string, csvDelimiter: string) => string;
-export declare const tableToArray: (table: HTMLTableElement) => any[][];
-export declare const tableToCSV: (table: HTMLTableElement, csvDelimiter?: string, csvNewLine?: string) => string;
-export declare const createDownloadLink: (anchor: HTMLAnchorElement, base64data: string, exporttype: string, filename: string) => boolean;
-export declare const string2ArrayBuffer: (s: string) => ArrayBuffer;
-export declare const removeColumns: (dataArray: any[][], columnIndexes: number[]) => void;
+export declare const b64toBlob: (b64Data: string, contentType: string, sliceSize?: number) => Blob;
+export declare const templates: {
+    excel: string;
+};
+/**
+ * Convert a string to Base64.
+ */
+export declare const base64: (s: string) => string;
+export declare const format: (s: string, context: any) => string;
+/**
+ * Get element by ID.
+ * @param {*} element
+ */
+export declare const getTable: (element: (HTMLTableElement | string)) => HTMLTableElement;
+/**
+ * Get element by ID.
+ * @param {*} element
+ */
+export declare const getAnchor: (element: (HTMLAnchorElement | string)) => HTMLAnchorElement;
+/**
+ * Encode a value for CSV.
+ * @param {*} value
+ */
+export declare const fixCSVField: (value: string, csvDelimiter: string) => string;
+export declare const tableToArray: (table: HTMLTableElement) => any[][];
+export declare const tableToCSV: (table: HTMLTableElement, csvDelimiter?: string, csvNewLine?: string) => string;
+export declare const createDownloadLink: (anchor: HTMLAnchorElement, base64data: string, exporttype: string, filename: string) => boolean;
+export declare const string2ArrayBuffer: (s: string) => ArrayBuffer;
+export declare const removeColumns: (dataArray: any[][], columnIndexes: number[]) => void;
+export declare const hasContent: (value: any) => boolean;

dist/utils.d.ts

@@ -0,0 +1,100 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta charset="utf-8">
+        <title>Export to excel test</title>
+        <script src="dist/excellentexport.js"></script>
+        <style>
+            table, tr, td {
+                border: 1px black solid;
+            }
+        </style>
+        <script>
+            function newApi(format) {
+                return ExcellentExport.convert({
+                    anchor: 'anchorNewApi-' + format,
+                    filename: 'data',
+                    format: format
+                }, [{
+                    name: 'Formatted Sheet',
+                    from: {
+                        table: 'datatable'
+                    },
+                    formats: [
+                        { range: "A2:A10", format: ExcellentExport.formats.INTEGER },
+                        { range: "B2:B10", format: ExcellentExport.formats.TEXT },
+                        { range: "C2:C10", format: ExcellentExport.formats.DATE },
+                        { range: "D2:D10", format: ExcellentExport.formats.DECIMAL },
+                        { range: "E2:E10", format: ExcellentExport.formats.BOOLEAN },
+                        { range: "F2:F10", format: ExcellentExport.formats.INTEGER },
+                        { range: "A5:E5", format: ExcellentExport.formats.TEXT },
+                        { range: "A6", format: ExcellentExport.formats.DECIMAL },
+                    ],
+                }]);
+            }
+        </script>
+    </head>
+    <body>
+        <h1>ExcellentExport.js</h1>
+
+        <h3>Test page</h3>
+
+        Test table:
+        <table id="datatable">
+            <tr>
+                <th>ID</th>
+                <th>Name</th>
+                <th>Birthdate</th>
+                <th>Salary</th>
+                <th>Active</th>
+                <th>Big number</th>
+            </tr>
+            <tr>
+                <td>1</td>
+                <td>John</td>
+                <td>1980-12-10</td>
+                <td>98762000.55</td>
+                <td>1</td>
+                <td>987654321987654</td>
+            </tr>
+            <tr>
+                <td>2</td>
+                <td>Peter</td>
+                <td>1978-01-23</td>
+                <td>98762500.43</td>
+                <td>0</td>
+                <td>876543219987654</td>
+            </tr>
+            <tr>
+                <td>3</td>
+                <td>George</td>
+                <td>1985-11-30</td>
+                <td>98761800.98</td>
+                <td>1</td>
+                <td>765432198987654</td>
+            </tr>
+            <tr>
+                <td>End</td>
+                <td>End</td>
+                <td>End</td>
+                <td>End</td>
+                <td>End</td>
+                <td>End</td>
+            </tr>
+            <tr>
+                <td>9876543.21</td>
+                <td></td>
+                <td></td>
+                <td></td>
+                <td></td>
+                <td></td>
+            </tr>
+        </table>
+
+        <br/>
+
+        <a href="#" id="anchorNewApi-xlsx" onclick="return newApi('xlsx');">Export Excel</a>
+        <a href="#" id="anchorNewApi-csv" onclick="return newApi('csv');">Export CSV</a>
+
+    </body>
+</html>

index.format.html

@@ -8,6 +8,7 @@
  */
 
 import * as XLSX from 'xlsx';
+import { CellType, FormatDefinition, PredefinedFormat } from './format';
 
 import * as utils from './utils';
 
@@ -29,17 +30,18 @@ export interface FromOptions {
     table?: (string|HTMLTableElement),
     array?: any[][],
 }
+
 export interface SheetOptions {
     name: string,
     from: FromOptions,
     removeColumns?: number[],
     filterRowFn?(row:any[]): boolean ,
     fixValue?(value:any, row:number, column:number): any,
     fixArray?(array:any[][]): any[][],
-    rtl?: boolean
+    rtl?: boolean,
+    formats?: (FormatDefinition | null)[],
 }
 
-
 const ExcellentExport = function() {
 
     const version = "3.8.1";
@@ -138,6 +140,35 @@ const ExcellentExport = function() {
             // Create sheet
             workbook.SheetNames.push(name);
             const worksheet = XLSX.utils.aoa_to_sheet(dataArray, {sheet: name} as XLSX.AOA2SheetOpts);
+            
+            // Apply format
+            if (sheetConf.formats) {
+                sheetConf.formats.forEach(f => {
+                    const range = XLSX.utils.decode_range(f.range);
+                    for (let R = range.s.r; R <= range.e.r; ++R) {
+                        for (let C = range.s.c; C <= range.e.c; ++C) {
+                            const cell = worksheet[XLSX.utils.encode_cell({r: R, c: C})];
+                            if (cell && utils.hasContent(cell.v)) {
+                                // type
+                                cell.t = f.format.type;
+
+                                // type fix
+                                if (f.format?.type == CellType.BOOLEAN) {
+                                    const v = cell.v.toString().toLowerCase();
+                                    if (v == 'true' || v == '1') cell.v = true;
+                                    if (v == 'false' || v == '0') cell.v = false;
+                                }
+                                // pattern
+                                if (f.format?.pattern) {
+                                    cell.z = f.format.pattern;
+                                }
+                            }
+                        }
+                    }
+                });
+            }
+                
+                
             workbook.Sheets[name] = worksheet;
             workbook.Views.push({RTL: options.rtl || sheetConf.rtl || false});
         });
@@ -177,6 +208,7 @@ const ExcellentExport = function() {
         version: function(): string {
             return version;
         },
+        formats: PredefinedFormat,
         excel: function(anchor:(HTMLAnchorElement|string), table:HTMLTableElement, name:string) {
             table = utils.getTable(table);
             anchor = utils.getAnchor(anchor);