From 76543faea9e0a6a09e46bf867450ca2bb42762bb Mon Sep 17 00:00:00 2001 From: SheetJS Date: Sat, 8 Apr 2023 20:20:50 -0400 Subject: [PATCH] angularjs --- .../docs/03-demos/01-frontend/07-angularjs.md | 307 ++++++++++++++++++ docz/docs/03-demos/01-frontend/09-legacy.md | 128 -------- docz/docs/03-demos/01-frontend/index.md | 2 +- docz/docs/03-demos/02-grid/index.md | 2 +- docz/docs/03-demos/index.md | 2 +- docz/static/angularjs/index.html | 94 ++++-- 6 files changed, 373 insertions(+), 162 deletions(-) create mode 100644 docz/docs/03-demos/01-frontend/07-angularjs.md diff --git a/docz/docs/03-demos/01-frontend/07-angularjs.md b/docz/docs/03-demos/01-frontend/07-angularjs.md new file mode 100644 index 0000000..02ddc00 --- /dev/null +++ b/docz/docs/03-demos/01-frontend/07-angularjs.md @@ -0,0 +1,307 @@ +--- +title: AngularJS +pagination_prev: demos/index +pagination_next: demos/grid/index +sidebar_position: 7 +--- + +:::warning + +This demo is for the legacy AngularJS framework (version 1). + +"Angular" now commonly refers to the new framework starting with version 2. +[The "Angular" demo](/docs/demos/frontend/angular) covers the new framework. + +::: + +AngularJS is a JS library for building user interfaces. + +## Demo + +:::note + +This demo was last run on 2023 April 08 using AngularJS `1.5.0` + +::: + +[Click here for a live standalone integration demo.](pathname:///angularjs/) + +The demo uses an array of objects as its internal state. It fetches and displays +data on load. It also includes a button for exporting data to file and a file +input element for loading user-submitted files. + +## Installation + +The [Standalone scripts](/docs/getting-started/installation/standalone) can be +referenced in a `SCRIPT` tag from the HTML entrypoint page. + +The `$http` service can request binary data using `"arraybuffer"` response type. +This maps to the `"array"` input format for `XLSX.read`: + +```js +app.controller('sheetjs', function($scope, $http) { + $http({ + method:'GET', url:'https://sheetjs.com/pres.xlsx', + // highlight-next-line + responseType:'arraybuffer' + }).then(function(data) { + // highlight-next-line + var wb = XLSX.read(data.data, {type:"array"}); + /* DO SOMETHING WITH wb HERE */ + $scope.data = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]); + }, function(err) { console.log(err); }); +}); +``` + +
Parsing User-Submitted Files (click to show) + +For file input elements, a general import directive is fairly straightforward: + +1) Add an `INPUT` element with attribute `import-sheet-js=""`: + +```html + +``` + +2) Define the `SheetJSImportDirective` directive function: + +```js +function SheetJSImportDirective() { return { + scope: false, + link: function ($scope, $elm) { + $elm.on('change', function (changeEvent) { + var reader = new FileReader(); + reader.onload = function (e) { + var wb = XLSX.read(e.target.result); + + /* DO SOMETHING WITH wb HERE */ + $scope.apply(function() { + $scope.data = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]); + }); + }; + reader.readAsArrayBuffer(changeEvent.target.files[0]); + }); + } +}; } +``` + +3) Define the `importSheetJs` directive in the app: + +```js +app.directive("importSheetJs", [SheetJSImportDirective]); +``` + +
+ +## Internal State + +The various SheetJS APIs work with various data shapes. The preferred state +depends on the application. + +### Array of Objects + +Typically, some users will create a spreadsheet with source data that should be +loaded into the site. This sheet will have known columns. For example, our +[presidents sheet](https://sheetjs.com/pres.xlsx) has "Name" / "Index" columns: + +![`pres.xlsx` data](pathname:///pres.png) + +This naturally maps to an array of typed objects, as in the example below: + +```js +app.controller('sheetjs', function($scope, $http) { + $http({ method:'GET', url:'https://sheetjs.com/pres.xlsx', responseType:'arraybuffer' }).then(function(data) { + var wb = XLSX.read(data.data, {type:"array"}); + // highlight-next-line + $scope.data = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]); + }, function(err) { console.log(err); }); +}); +``` + +`data` will be an array of objects: + +```js +[ + { Name: "Bill Clinton", Index: 42 }, + { Name: "GeorgeW Bush", Index: 43 }, + { Name: "Barack Obama", Index: 44 }, + { Name: "Donald Trump", Index: 45 }, + { Name: "Joseph Biden", Index: 46 } +] +``` + +A component will typically loop over the data using `ng-repeat`. The following +template generates a TABLE with a row for each President: + +```html + + + + + + +
NameIndex
{{row.Name}}{{row.Index}}
+``` + +`XLSX.utils.json_to_sheet` can generate a worksheet from the data: + +```js +/* assuming $scope.data is an array of objects */ +$scope.exportSheetJS = function() { + /* generate a worksheet */ + var ws = XLSX.utils.json_to_sheet($scope.data); + /* add to workbook */ + var wb = XLSX.utils.book_new(); + XLSX.utils.book_append_sheet(wb, ws, "Presidents"); + /* write workbook and force a download */ + XLSX.writeFile(wb, "SheetJSAngularJSAoO.xlsx"); +}; +``` + +
Complete Example (click to show) + +1) Save the following to `index.html`: + +```html title="index.html" + + + + SheetJS + AngularJS + + + + + +

SheetJS + AngularJS demo

+ +
+ + + + + + + +
NameIndex
{{row.Name}}{{row.Index}}
+
+ + + + +``` + +2) Start a local web server with `npx http-server .` and access the displayed +URL with a web browser (typically `http://localhost:8080`) + +
+ +### HTML + +The main disadvantage of the Array of Objects approach is the specific nature +of the columns. For more general use, passing around an Array of Arrays works. +However, this does not handle merge cells well! + +The `sheet_to_html` function generates HTML that is aware of merges and other +worksheet features. The generated HTML does not contain any ` +``` + +The HTML table can be directly exported with `XLSX.utils.table_to_book`: + +```js + $scope.exportSheetJS = function() { + /* export table element */ + // highlight-start + var tbl = document.getElementById("tbl").getElementsByTagName("TABLE")[0]; + var wb = XLSX.utils.table_to_book(tbl); + // highlight-end + XLSX.writeFile(wb, "SheetJSAngularJSHTML.xlsx"); + }; +``` + +
Complete Example (click to show) + +1) Save the following to `index.html`: + +```html title="index.html" + + + + SheetJS + AngularJS + + + + + + +

SheetJS + AngularJS demo

+ +
+ +
+
+ + + + +``` + +2) Start a local web server with `npx http-server .` and access the displayed +URL with a web browser (typically `http://localhost:8080`) + +
diff --git a/docz/docs/03-demos/01-frontend/09-legacy.md b/docz/docs/03-demos/01-frontend/09-legacy.md index b0f8cee..d8ae077 100644 --- a/docz/docs/03-demos/01-frontend/09-legacy.md +++ b/docz/docs/03-demos/01-frontend/09-legacy.md @@ -177,134 +177,6 @@ included in the page and the relevant features are enabled on the target system. ## Frameworks -### AngularJS - -AngularJS was a front-end MVC framework that was discontinued by Google in 2022. -It should not be confused with the modern framework "Angular". - -The [Live demo](pathname:///angularjs/index.html) shows a simple table that is -updated with file data and exported to spreadsheets. - -This demo uses AngularJS 1.5.0. - -
Full Exposition (click to show) - -**Array of Objects** - -A common data table is often stored as an array of objects: - -```js -$scope.data = [ - { Name: "Bill Clinton", Index: 42 }, - { Name: "GeorgeW Bush", Index: 43 }, - { Name: "Barack Obama", Index: 44 }, - { Name: "Donald Trump", Index: 45 } -]; -``` - -This neatly maps to a table with `ng-repeat`: - -```html - - - - - - -
NameIndex
{{row.Name}}{{row.Index}}
-``` - -The `$http` service can request binary data using the `"arraybuffer"` response -type coupled with `XLSX.read` with type `"array"`: - -```js - $http({ - method:'GET', - url:'https://sheetjs.com/pres.xlsx', - responseType:'arraybuffer' - }).then(function(data) { - var wb = XLSX.read(data.data, {type:"array"}); - var d = XLSX.utils.sheet_to_json(wb.Sheets[wb.SheetNames[0]]); - $scope.data = d; - }, function(err) { console.log(err); }); -``` - -The HTML table can be directly exported with `XLSX.utils.table_to_book`: - -```js -var wb = XLSX.utils.table_to_book(document.getElementById('sjs-table')); -XLSX.writeFile(wb, "export.xlsx"); -``` - - -**Import Directive** - -A general import directive is fairly straightforward: - -- Define the `importSheetJs` directive in the app: - -```js -app.directive("importSheetJs", [SheetJSImportDirective]); -``` - -- Add the attribute `import-sheet-js=""` to the file input element: - -```html - -``` - -- Define the directive: - -```js -function SheetJSImportDirective() { - return { - scope: { opts: '=' }, - link: function ($scope, $elm) { - $elm.on('change', function (changeEvent) { - var reader = new FileReader(); - - reader.onload = function (e) { - /* read workbook */ - var ab = e.target.result; - var workbook = XLSX.read(ab); - - /* DO SOMETHING WITH workbook HERE */ - }; - - reader.readAsArrayBuffer(changeEvent.target.files[0]); - }); - } - }; -} -``` - - -**Export Service** - -An export can be triggered at any point! Depending on how data is represented, -a workbook object can be built using the utility functions. For example, using -an array of objects: - -```js -/* starting from this data */ -var data = [ - { name: "Barack Obama", pres: 44 }, - { name: "Donald Trump", pres: 45 } -]; - -/* generate a worksheet */ -var ws = XLSX.utils.json_to_sheet(data); - -/* add to workbook */ -var wb = XLSX.utils.book_new(); -XLSX.utils.book_append_sheet(wb, ws, "Presidents"); - -/* write workbook and force a download */ -XLSX.writeFile(wb, "sheetjs.xlsx"); -``` - -
- ### Dojo Toolkit _Live Demos_ diff --git a/docz/docs/03-demos/01-frontend/index.md b/docz/docs/03-demos/01-frontend/index.md index 37f1afd..841110f 100644 --- a/docz/docs/03-demos/01-frontend/index.md +++ b/docz/docs/03-demos/01-frontend/index.md @@ -27,7 +27,7 @@ Demos for popular frameworks are included in separate pages: ); })} -Legacy frameworks including old AngularJS are covered [in the "Legacy" section](/docs/demos/frontend/legacy). +Legacy frameworks including Dojo are covered [in the "Legacy" section](/docs/demos/frontend/legacy). :::note Recommendation diff --git a/docz/docs/03-demos/02-grid/index.md b/docz/docs/03-demos/02-grid/index.md index c00d9c2..329cce6 100644 --- a/docz/docs/03-demos/02-grid/index.md +++ b/docz/docs/03-demos/02-grid/index.md @@ -58,7 +58,7 @@ through a special Export button. It handles the SheetJS operations internally. This UI Grid is for AngularJS, not the modern Angular. New projects should not use AngularJS. This demo is included for legacy applications. -The [AngularJS demo](/docs/demos/frontend/legacy#angularjs) covers more general strategies. +The [AngularJS demo](/docs/demos/frontend/angularjs) covers more general strategies. ::: diff --git a/docz/docs/03-demos/index.md b/docz/docs/03-demos/index.md index 3afa36d..4f7af16 100644 --- a/docz/docs/03-demos/index.md +++ b/docz/docs/03-demos/index.md @@ -26,7 +26,7 @@ run in the web browser, demos will include interactive examples. - [`React`](/docs/demos/frontend/react) - [`Svelte`](/docs/demos/frontend/svelte) - [`VueJS`](/docs/demos/frontend/vue) -- [`Angular.JS`](/docs/demos/frontend/legacy#angularjs) +- [`Angular.JS`](/docs/demos/frontend/angularjs) - [`Dojo`](/docs/demos/frontend/legacy#dojo-toolkit) - [`Knockout`](/docs/demos/frontend/legacy#knockoutjs) diff --git a/docz/static/angularjs/index.html b/docz/static/angularjs/index.html index 3ad4cb1..a70f569 100644 --- a/docz/static/angularjs/index.html +++ b/docz/static/angularjs/index.html @@ -10,57 +10,89 @@ + -
-SheetJS + AngularJS demo
-
-The core library can be used as-is in AngularJS applications.
-The Community Edition README details some common use cases.
-We also have some more public demos
+
SheetJS + AngularJS demo

+

+The core library can be used as-is in AngularJS applications. The SheetJS + AngularJS demo covers common strategies.


 
 This demo shows:
-- $http request for XLSX file and scope update with data
-- HTML table using ng-repeat
-- XLSX table export using `XLSX.utils.table_to_book`
-
+
+

 Sample Spreadsheet
-
+


 The table has hardcoded fields `Name` and `Index`.
-
-
- +

+Testing
+
    +
  1. Load page. The table should show a list of presidents.
    2. +
  2. Click "Export Table" and confirm that a file was downloaded.
    3. +
  3. Open the generated file in a spreadsheet editor and add a new row.
    4. +
  4. Use the file input element to select the edited file. The table should refresh.
    5. +
+
- - - - - - - -
NameIndex
{{row.Name}}{{row.Index}}
- - - +
+ + + + + + +
NameIndex
{{row.Name}}{{row.Index}}
+