docs.sheetjs.com/docz/docs/03-demos/05-mobile/04-ionic.md

456 lines
12 KiB
Markdown
Raw Normal View History

2023-01-05 23:33:49 +00:00
---
2023-09-11 04:44:15 +00:00
title: Data Conduction in Ionic Apps
sidebar_label: Ionic
description: Build data-intensive mobile apps with Ionic and Cordova. Seamlessly integrate spreadsheets into your app using SheetJS. Let data in your Excel spreadsheets shine.
2023-02-28 11:40:44 +00:00
pagination_prev: demos/static/index
2023-01-05 23:33:49 +00:00
pagination_next: demos/desktop/index
sidebar_position: 4
sidebar_custom_props:
summary: Native Components + Web View
---
2023-04-27 09:12:19 +00:00
import current from '/version.js';
2023-04-29 11:21:37 +00:00
import CodeBlock from '@theme/CodeBlock';
2023-04-27 09:12:19 +00:00
2023-09-11 04:44:15 +00:00
[Ionic](https://ionicframework.com/) is a mobile app framework for building iOS
and Android apps with the Cordova platform.
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
[SheetJS](https://sheetjs.com) is a JavaScript library for reading and writing
data from spreadsheets.
This demo uses Ionic and SheetJS to process data and generate spreadsheets.
We'll explore how to load SheetJS in an Ionic app and use Ionic APIs and plugins
to extract data from, and write data to, spreadsheet files on the device.
The ["Demo"](#demo) creates an app that looks like the screenshots below:
2023-03-20 05:44:17 +00:00
<table><thead><tr>
<th><a href="#demo">iOS</a></th>
2023-03-29 00:26:39 +00:00
<th><a href="#demo">Android</a></th>
2023-03-20 05:44:17 +00:00
</tr></thead><tbody><tr><td>
![iOS screenshot](pathname:///ionic/ios.png)
2023-03-29 00:26:39 +00:00
</td><td>
![Android screenshot](pathname:///ionic/and.png)
2023-03-20 05:44:17 +00:00
</td></tr></tbody></table>
2023-09-11 04:44:15 +00:00
:::info pass
This demo covers Ionic apps using the Cordova platform.
The [CapacitorJS demo](/docs/demos/mobile/capacitor) covers CapacitorJS apps.
:::
2023-03-20 05:44:17 +00:00
2023-01-05 23:33:49 +00:00
:::warning Telemetry
Before starting this demo, manually disable telemetry. On Linux and MacOS:
```bash
rm -rf ~/.ionic/
mkdir ~/.ionic
cat <<EOF > ~/.ionic/config.json
{
"version": "6.20.1",
"telemetry": false,
"npmClient": "npm"
}
EOF
npx @capacitor/cli telemetry off
```
To verify telemetry was disabled:
```bash
npx @ionic/cli config get -g telemetry
npx @capacitor/cli telemetry
```
:::
2023-03-20 05:44:17 +00:00
## Integration Details
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
The [SheetJS NodeJS Module](/docs/getting-started/installation/nodejs) can be
imported from the main entrypoint or any script in the project.
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
### Internal State
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
The ["Angular" demo](/docs/demos/frontend/angular) discusses a number of state
representations and preview strategies.
For this demo, the internal state is an "array of arrays"[^1] (`any[][]`):
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
```ts title="Array of Arrays state"
import { Component } from '@angular/core';
type AOA = any[][];
2023-03-20 05:44:17 +00:00
2023-09-11 04:44:15 +00:00
@Component({...})
export class SheetJSTablePage {
data: AOA = [
["S", "h", "e", "e", "t", "J", "S"],
[ 5, 4, 3, 3, 7, 9, 5]
];
// ...
}
```
### Displaying Data
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
`ion-grid`[^2] is a display grid component. The Angular `ngFor` directive[^3]
simplifies iteration over the array of arrays:
```html title="Template for displaying an array of arrays"
2023-01-05 23:33:49 +00:00
<ion-grid>
<ion-row *ngFor="let row of data">
<ion-col *ngFor="let val of row">
{{val}}
</ion-col>
</ion-row>
</ion-grid>
```
2023-09-11 04:44:15 +00:00
### File Operations
`@awesome-cordova-plugins/file` reads and writes files on devices.
2023-03-20 05:44:17 +00:00
2023-09-11 04:44:15 +00:00
:::info pass
2023-03-20 05:44:17 +00:00
2023-09-11 04:44:15 +00:00
The plugins in the `@ionic-native` scope have been deprecated. The community
modules in the `@awesome-cordova-plugins` scope should be used.
2023-03-20 05:44:17 +00:00
2023-09-11 04:44:15 +00:00
:::
#### Reading Files
`this.file.readAsArrayBuffer` reads file data from a specified URL and resolves
to `ArrayBuffer` objects.
These objects can be parsed with the SheetJS `read` method[^4]. The SheetJS
`sheet_to_json` method[^5] with the option `header: 1` generates an array of
arrays which can be assigned to the page state:
2023-01-05 23:33:49 +00:00
```ts
2023-09-11 04:44:15 +00:00
/* read a workbook file */
2023-01-05 23:33:49 +00:00
const ab: ArrayBuffer = await this.file.readAsArrayBuffer(url, filename);
2023-09-11 04:44:15 +00:00
/* parse */
2023-03-20 05:44:17 +00:00
const wb: XLSX.WorkBook = XLSX.read(ab, {type: 'array'});
2023-09-11 04:44:15 +00:00
/* generate an array of arrays from the first worksheet */
const ws: XLSX.WorkSheet = wb.SheetNames[wb.Sheets[0]];
const aoa: AOA = XLSX.utils.sheet_to_json(ws, {header: 1});
/* update state */
this.data = aoa;
2023-03-20 05:44:17 +00:00
```
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
#### Writing Files
2023-03-20 05:44:17 +00:00
2023-09-11 04:44:15 +00:00
`this.file.writeFile` writes file data stored in `Blob` objects to the device.
2023-03-20 05:44:17 +00:00
2023-09-11 04:44:15 +00:00
From the array of arrays, the SheetJS `aoa_to_sheet` method[^6] generates a
worksheet object. The `book_new` and `book_append_sheet` helpers[^7] generate a
workbook object. The SheetJS `write` method[^8] with the option `type: "array"`
will generate an `ArrayBuffer`, from which a `Blob` can be created:
2023-03-20 05:44:17 +00:00
```ts
2023-09-11 04:44:15 +00:00
/* generate worksheet */
const ws: XLSX.WorkSheet = XLSX.utils.aoa_to_sheet(this.data);
/* generate workbook and add the worksheet */
const wb: XLSX.WorkBook = XLSX.utils.book_new();
XLSX.utils.book_append_sheet(wb, ws, 'SheetJS');
/* write XLSX to ArrayBuffer */
const ab: ArrayBuffer = XLSX.write(wb, { bookType: 'xlsx', type: 'array' });
/* generate Blob */
let blob = new Blob([ab], {type: 'application/octet-stream'});
/* write Blob to device */
2023-01-05 23:33:49 +00:00
this.file.writeFile(url, filename, blob, {replace: true});
```
## Demo
:::note
2023-09-11 04:44:15 +00:00
The project was last tested in 2023 September 10. `ionic info` showed:
- Ionic: `@ionic/angular 7.3.3`, `@ionic/angular-toolkit 9.0.0`
- Cordova: `cordova-lib@12.0.1`, `android 12.0.1, ios 7.0.1`
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
The file integration uses `@awesome-cordova-plugins/file` version `6.4.0`.
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
The iOS demo was last tested on 2023 September 10 on an emulated iPhone SE
(3rd generation) + iOS 16.4
The Android demo was last tested on 2023 September 10 on an emulated Pixel 3 +
Android 13 ("Tiramisu") API 33.
2023-03-29 00:26:39 +00:00
2023-01-05 23:33:49 +00:00
:::
2023-09-11 04:44:15 +00:00
The app in this demo will display data in a table.
On load, a [test file](https://sheetjs.com/pres.numbers) will be processed.
When a document is selected with the file picker, it will be processed and the
table will refresh to show the contents.
"Import Data" will attempt to read `SheetJSIonic.xlsx` from a known location. An
alert will display the expected location.
"Export Data" will attempt to export the table data to `SheetJSIonic.xlsx` in a
known location. After writing, an alert will display the location of the file.
### Platform Setup
2023-01-05 23:33:49 +00:00
0) Disable telemetry as noted in the warning.
2023-09-11 04:44:15 +00:00
1) Follow the official instructions for iOS and Android development[^9].
2) Install required global dependencies:
2023-01-05 23:33:49 +00:00
```bash
2023-03-29 00:26:39 +00:00
npm i -g cordova-res @angular/cli native-run @ionic/cli
2023-01-05 23:33:49 +00:00
```
2023-09-11 04:44:15 +00:00
### Base Project
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
3) Create a new project:
2023-01-05 23:33:49 +00:00
```bash
2023-03-29 00:26:39 +00:00
ionic start SheetJSIonic blank --type angular --cordova --quiet --no-git --no-link --confirm
2023-01-05 23:33:49 +00:00
```
2023-09-11 04:44:15 +00:00
When asked to select `NgModules` or `Standalone Components`, select `NgModules`
2023-03-20 05:44:17 +00:00
If a prompt asks to confirm Cordova use, enter `Yes` to continue.
2023-01-05 23:33:49 +00:00
If a prompt asks about creating an Ionic account, enter `N` to opt out.
2023-09-11 04:44:15 +00:00
4) Set up Cordova:
2023-01-05 23:33:49 +00:00
```bash
2023-03-20 05:44:17 +00:00
cd SheetJSIonic
2023-03-29 00:26:39 +00:00
ionic cordova plugin add cordova-plugin-file
ionic cordova platform add ios --confirm
ionic cordova platform add android --confirm
2023-09-11 04:44:15 +00:00
npm i --save @awesome-cordova-plugins/core @awesome-cordova-plugins/file @ionic/cordova-builders
2023-01-05 23:33:49 +00:00
```
2023-09-11 04:44:15 +00:00
:::note pass
2023-03-20 05:44:17 +00:00
2023-03-29 00:26:39 +00:00
If `cordova-plugin-file` is added before the platforms, installation may fail:
2023-03-20 05:44:17 +00:00
```
CordovaError: Could not load API for ios project
```
2023-03-29 00:26:39 +00:00
This can be resolved by removing and reinstalling the `ios` platform:
2023-03-20 05:44:17 +00:00
```bash
2023-03-29 00:26:39 +00:00
ionic cordova platform rm ios
ionic cordova platform add ios --confirm
```
:::
2023-09-11 04:44:15 +00:00
:::caution pass
2023-03-29 00:26:39 +00:00
2023-09-11 04:44:15 +00:00
If the `npm i` step fails due to `rxjs` resolution, add the highlighted lines
2023-03-29 00:26:39 +00:00
to `package.json` to force a resolution:
```js title="package.json"
"private": true,
// highlight-start
"overrides": {
"rxjs": "~7.5.0"
},
// highlight-end
"dependencies": {
2023-03-20 05:44:17 +00:00
```
2023-09-11 04:44:15 +00:00
Note that the required `rxjs` version will be displayed in the error log.
2023-05-07 13:58:36 +00:00
After adding the lines, the `npm i` command will succeed.
2023-03-29 00:26:39 +00:00
2023-03-20 05:44:17 +00:00
:::
2023-09-11 04:44:15 +00:00
5) Install dependencies:
2023-01-05 23:33:49 +00:00
2023-04-29 11:21:37 +00:00
<CodeBlock language="bash">{`\
2023-05-07 13:58:36 +00:00
npm i --save https://cdn.sheetjs.com/xlsx-${current}/xlsx-${current}.tgz`}
2023-04-29 11:21:37 +00:00
</CodeBlock>
2023-01-05 23:33:49 +00:00
2023-09-11 04:44:15 +00:00
6) Add `@awesome-cordova-plugins/file` to the module. Differences highlighted below:
2023-01-05 23:33:49 +00:00
```ts title="src/app/app.module.ts"
import { AppComponent } from './app.component';
import { AppRoutingModule } from './app-routing.module';
// highlight-next-line
2023-09-11 04:44:15 +00:00
import { File } from '@awesome-cordova-plugins/file/ngx';
2023-01-05 23:33:49 +00:00
@NgModule({
declarations: [AppComponent],
imports: [BrowserModule, IonicModule.forRoot(), AppRoutingModule],
// highlight-next-line
providers: [File, { provide: RouteReuseStrategy, useClass: IonicRouteStrategy }],
bootstrap: [AppComponent],
})
export class AppModule {}
```
2023-09-11 04:44:15 +00:00
7) Download [`home.page.ts`](pathname:///ionic/home.page.ts) and replace:
2023-01-05 23:33:49 +00:00
```bash
curl -o src/app/home/home.page.ts -L https://docs.sheetjs.com/ionic/home.page.ts
```
2023-09-11 04:44:15 +00:00
### iOS
8) Enable file sharing and make the documents folder visible in the iOS app.
Add the following lines to `platforms/ios/SheetJSIonic/SheetJSIonic-Info.plist`:
```xml title="platforms/ios/SheetJSIonic/SheetJSIonic-Info.plist (add to file)"
<plist version="1.0">
<dict>
<!-- highlight-start -->
<key>UIFileSharingEnabled</key>
<true/>
<key>LSSupportsOpeningDocumentsInPlace</key>
<true/>
<!-- highlight-end -->
<key>CFBundleDevelopmentRegion</key>
```
(The root element of the document is `plist` and it contains one `dict` child)
9) Build the app and start the simulator
2023-01-05 23:33:49 +00:00
```bash
2023-03-29 00:26:39 +00:00
ionic cordova emulate ios
2023-01-05 23:33:49 +00:00
```
2023-09-11 04:44:15 +00:00
When the app is loaded, a list of Presidents should be displayed. This list is
dynamically generated by fetching and parsing a test file.
:::caution pass
2023-01-05 23:33:49 +00:00
2023-03-20 05:44:17 +00:00
In some test runs, the `cordova build ios --emulator` step failed with error:
```
> cordova build ios --emulator
Could not load API for ios project
```
This was resolved by forcefully installing `cordova-ios`:
```bash
npm i --save cordova-ios
```
:::
2023-03-29 00:26:39 +00:00
2023-09-11 04:44:15 +00:00
:::info pass
In the most recent test, the `native-run ios` command failed with
```
[native-run] ERR_UNKNOWN: Path 'platforms/ios/build/emulator/SheetJSIonic.app' not found
```
Inspecting `platforms/ios/build/`, the actual folder name was:
```bash
% ls platforms/ios/build
#highlight-next-line
Debug-iphonesimulator
```
The iOS simulator can be launched manually:
```bash
native-run ios --app platforms/ios/build/Debug-iphonesimulator/SheetJSIonic.app --virtual
```
:::
### Android
10) Enable file reading and writing in the Android app.
Edit `platforms/android/app/src/main/AndroidManifest.xml` and add the following
two lines before the `application` tag:
```xml title="platforms/android/app/src/main/AndroidManifest.xml (add to file)"
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
```
In the `application` tag, add the attribute `android:requestLegacyExternalStorage="true"`.
11) Build the app and start the emulator
2023-03-29 00:26:39 +00:00
```bash
ionic cordova emulate android
```
2023-09-11 04:44:15 +00:00
When the app is loaded, a list of Presidents should be displayed. This list is
dynamically generated by fetching and parsing a test file.
:::caution pass
2023-03-29 00:26:39 +00:00
In some test runs, `cordova build android --emulator` step failed with error:
```
Could not find or parse valid build output file
```
This was resolved by forcefully installing `cordova-android`:
```bash
npm i --save cordova-android
```
:::
2023-09-11 04:44:15 +00:00
:::caution pass
In some tests, the build failed with a Gradle error:
```
Could not find an installed version of Gradle either in Android Studio,
or on your system to install the gradle wrapper. Please include gradle
in your path or install Android Studio
```
On macOS, this issue was resolved by installing gradle with Homebrew manager:
```bash
brew install gradle
```
:::
:::warning pass
When the demo was last tested on Android, reading files worked as expected.
However, the generated files were not externally visible from the Files app.
**This is a known bug with Android SDK 33 and the underlying file plugins!**
:::
[^1]: See ["Array of Arrays" in the API reference](/docs/api/utilities/array#array-of-arrays)
[^2]: See [`ion-grid`](https://ionicframework.com/docs/api/grid) in the Ionic documentation.
[^3]: See [`ngFor`](https://angular.io/api/common/NgFor) in the Angular documentation.
[^4]: See [`read` in "Reading Files"](/docs/api/parse-options)
[^5]: See ["Array Output" in "Utility Functions"](/docs/api/utilities/array#array-output)
[^6]: See [`aoa_to_sheet` in "Utilities"](/docs/api/utilities/array#array-of-arrays-input)
[^7]: See ["Workbook Helpers" in "Utilities"](/docs/api/utilities/wb) for details on `book_new` and `book_append_sheet`.
[^8]: See [`write` in "Writing Files"](/docs/api/write-options)
[^9]: See ["Developing for iOS"](https://ionicframework.com/docs/v6/developing/ios) and ["Developing for Android"](https://ionicframework.com/docs/v6/developing/android) in the v6 Ionic framework documentation.