Skip to content

Commit 59895eb

Browse files
OS-pedrogustavobilroOS-pedrogustavobilro
authored
feat!: Plugin implementation (#1)
* feat: Add plugin API * feat(android): Implement bridge * feat(ios): Implement bridge Including xcframework * fix: Calling fileviewer operations from Main * fix(ios): closure usage * docs: Add READMEs * docs: Update CONTRIBUTING * chore: Typos in README References: https://outsystemsrd.atlassian.net/browse/RMET-4056 * chore: Add code comment
1 parent 5f2e619 commit 59895eb

File tree

46 files changed

+5185
-86
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

46 files changed

+5185
-86
lines changed

‎CONTRIBUTING.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,71 @@
11
# Contributing
22

33
This guide provides instructions for contributing to this Capacitor plugin.
4+
5+
## Native code
6+
7+
This repository contains minimal code for native Android and iOS. The implementation for native mobile exists in separate repositories:
8+
9+
- [Contributing for Android](https://github.com/ionic-team/ion-android-fileviewer?tab=readme-ov-file#contributing)
10+
- [Contributing for iOS](https://github.com/ionic-team/ion-ios-fileviewer?tab=readme-ov-file#contributing)
11+
12+
## Developing
13+
14+
### Local Setup
15+
16+
1. Fork and clone the repo, uncheking the clone `main` branch only option.
17+
2. If you plan to create a new feature or fix a bug, checkout `development` branch (in general Pull Requests should be open for that branch).
18+
3. Install the dependencies.
19+
20+
```shell
21+
npm install
22+
```
23+
24+
4. Install SwiftLint if you're on macOS.
25+
26+
```shell
27+
brew install swiftlint
28+
```
29+
30+
### Scripts
31+
32+
#### `npm run build`
33+
34+
Build the plugin web assets and generate plugin API documentation using [`@capacitor/docgen`](https://github.com/ionic-team/capacitor-docgen).
35+
36+
It will compile the TypeScript code from `src/` into ESM JavaScript in `dist/esm/`. These files are used in apps with bundlers when your plugin is imported.
37+
38+
Then, Rollup will bundle the code into a single file at `dist/plugin.js`. This file is used in apps without bundlers by including it as a script in `index.html`.
39+
40+
#### `npm run verify`
41+
42+
Build and validate the web and native projects.
43+
44+
This is useful to run in CI to verify that the plugin builds for all platforms.
45+
46+
#### `npm run lint` / `npm run fmt`
47+
48+
Check formatting and code quality, autoformat/autofix if possible.
49+
50+
This template is integrated with ESLint, Prettier, and SwiftLint. Using these tools is completely optional, but the [Capacitor Community](https://github.com/capacitor-community/) strives to have consistent code style and structure for easier cooperation.
51+
52+
## Commits/PR's
53+
54+
Commits and PR's should use the [conventional-commits](https://www.conventionalcommits.org/) format so the release process can version and create changelog correctly.
55+
56+
## Publishing
57+
58+
Publishing is automated based on the branch committed to. When a commit or merge is made to a branch a release that corresponds with the branch will be created:
59+
60+
| Branch Name | Build Type | NPM Tag | Example NPM Version |
61+
| ----------- | ----------------------------- | ------- | ---------------------------------- |
62+
| development | dev | dev | @capacitor/file-viewer@1.0.0-dev.1 |
63+
| next | next (these are betas/alphas) | next | @capacitor/file-viewer@1.0.0-next.1 |
64+
| main | latest | latest | @capacitor/file-viewer@1.0.0 |
65+
66+
- Dev work should be done by creating and merging PR's into the `development` branch until a feature set is complete enough to form a release.
67+
- When a feature set is complete enough to form a release, merge the `development` branch into the `next` branch where it becomes a beta/alpha tagged under `next` for testing teams to use before full release. In case a PR is opened from `development` to `next`, avoid squashing the commits, to keep the history.
68+
- Upon completed testing the `next` branch is merged into `main` for a full release to be made. In case a PR is opened from `next` to `main`, avoid squashing the commits, to keep the history.
69+
- The `main` branch should then be merged into `dev` and `next` to keep them up to date with the latest code base.
70+
71+
> **Note**: The [`files`](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#files) array in `package.json` specifies which files get published. If you rename files/directories or add files elsewhere, you may need to update it.

‎README.md

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,56 @@
11
# capacitor-file-viewer
2-
File Viewer plugin for Capacitor ⚡️
2+
3+
<div align="center">
4+
<a href="https://github.com/ionic-team/capacitor-file-viewer">
5+
<img src=".github/assets/logo.png" alt="Logo" width="auto" height="100">
6+
</a>
7+
8+
<h3 align="center">@capacitor/file-viewer</h3>
9+
10+
<p align="center">
11+
The FileViewer API provides mechanisms for opening files and previewing media. Not available on web.
12+
<br />
13+
<a href="https://github.com/ionic-team/cordova-outsystems-file-viewer">🔌 Cordova Plugin</a>
14+
·
15+
<a href="https://github.com/ionic-team/ion-android-fileviewer">🤖 Android Library</a>
16+
·
17+
<a href="https://github.com/ionic-team/ion-ios-fileviewer">🍏 iOS Library</a>
18+
</p>
19+
<p align="center">
20+
<a href="https://github.com/ionic-team/capacitor-file-viewer/issues/new?labels=bug&template=bug-report.md">🐛 Report Bug</a>
21+
·
22+
<a href="https://github.com/ionic-team/capacitor-file-viewer/issues/new?labels=enhancement&template=feature-request.md"> 💡 Request Feature</a>
23+
</p>
24+
</div>
25+
26+
## Install
27+
28+
```bash
29+
npm install @capacitor/file-viewer
30+
npx cap sync
31+
```
32+
33+
## Example
34+
35+
```typescript
36+
import { FileViewer } from "@capacitor/file-viewer";
37+
38+
// can use a plugin like @capacitor/filesystem to get the full path to the file
39+
const openDocument = async () => {
40+
await FileViewer.openDocumentFromLocalPath({
41+
path: "path/to/file.pdf"
42+
});
43+
};
44+
45+
// ios-specific
46+
const previewMedia = async () => {
47+
await FileViewer.previewMediaContentFromUrl({
48+
path: "https://url_hosting_media/file.mp4"
49+
});
50+
}
51+
```
52+
53+
## API
54+
55+
Check the plugin's api [here](packages/capacitor-plugin/README.md).
56+

‎packages/capacitor-plugin/CapacitorFileViewer.podspec

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ Pod::Spec.new do |s|
1313
s.source_files = 'ios/Sources/FileViewerPlugin/*.{swift,h,m,c,cc,mm,cpp}'
1414
s.ios.deployment_target = '14.0'
1515
#s.dependency 'FileViewerLib', spec='~> 1.0'
16+
# temporary xcframeowrk dependency - TODO update to official pod (commented line above) once published
17+
s.vendored_frameworks = 'ios/Sources/*/IONFileViewerLib.xcframework'
1618
s.dependency 'Capacitor'
1719
s.swift_version = '5.1'
1820
end

‎packages/capacitor-plugin/Package.swift

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,18 @@ let package = Package(
1313
.package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", branch: "7.0.0")
1414
],
1515
targets: [
16+
.binaryTarget(
17+
name: "IONFileViewerLib",
18+
// url: "https://github.com/ionic-team/ion-ios-fileviewer/releases/download/1.0.0/IONFileViewerLib.zip",
19+
// checksum: "<compute_checksum>" // sha-256
20+
path: "./ios/Sources/FileViewerPlugin/IONFileViewerLib.xcframework"
21+
),
1622
.target(
1723
name: "FileViewerPlugin",
1824
dependencies: [
1925
.product(name: "Capacitor", package: "capacitor-swift-pm"),
20-
.product(name: "Cordova", package: "capacitor-swift-pm")
26+
.product(name: "Cordova", package: "capacitor-swift-pm"),
27+
"IONFileViewerLib"
2128
],
2229
path: "ios/Sources/FileViewerPlugin"),
2330
.testTarget(

‎packages/capacitor-plugin/README.md

Lines changed: 194 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,48 @@
11
# @capacitor/file-viewer
22

3+
The FileViewer API provides mechanisms for opening files and previewing media. Not available on web.
4+
5+
The media preview methods are currently only supported on iOS. It uses a built-in player.
6+
7+
## Install
8+
9+
```bash
10+
npm install @capacitor/file-viewer
11+
npx cap sync
12+
```
13+
14+
## Example
15+
16+
```typescript
17+
import { FileViewer } from "@capacitor/file-viewer";
18+
19+
// can use a plugin like @capacitor/filesystem to get the full path to the file
20+
const openDocument = async () => {
21+
await FileViewer.openDocumentFromLocalPath({
22+
path: "path/to/file.pdf"
23+
});
24+
};
25+
26+
// ios-specific
27+
const previewMedia = async () => {
28+
await FileViewer.previewMediaContentFromUrl({
29+
path: "https://url_hosting_media/file.mp4"
30+
});
31+
}
32+
```
33+
334
## API
435

536
<docgen-index>
637

7-
* [`echo(...)`](#echo)
38+
* [`openDocumentFromLocalPath(...)`](#opendocumentfromlocalpath)
39+
* [`openDocumentFromResources(...)`](#opendocumentfromresources)
40+
* [`openDocumentFromUrl(...)`](#opendocumentfromurl)
41+
* [`previewMediaContentFromLocalPath(...)`](#previewmediacontentfromlocalpath)
42+
* [`previewMediaContentFromResources(...)`](#previewmediacontentfromresources)
43+
* [`previewMediaContentFromUrl(...)`](#previewmediacontentfromurl)
44+
* [Interfaces](#interfaces)
45+
* [Type Aliases](#type-aliases)
846

947
</docgen-index>
1048

@@ -13,22 +51,171 @@ For list of existing error codes, see [Errors](#errors).
1351
<docgen-api>
1452
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
1553

16-
### echo(...)
54+
File Viewer API
55+
56+
Only available in Native Android and iOS; not available for Web / PWAs.
57+
58+
### openDocumentFromLocalPath(...)
59+
60+
```typescript
61+
openDocumentFromLocalPath(options: OpenFromLocalPathOptions) => Promise<void>
62+
```
63+
64+
Open a file stored in the local file system
65+
66+
| Param | Type |
67+
| ------------- | ----------------------------------------------------------------------------- |
68+
| **`options`** | <code><a href="#openfromlocalpathoptions">OpenFromLocalPathOptions</a></code> |
69+
70+
**Since:** 1.0.0
71+
72+
--------------------
73+
74+
75+
### openDocumentFromResources(...)
76+
77+
```typescript
78+
openDocumentFromResources(options: OpenFromResourcesOptions) => Promise<void>
79+
```
80+
81+
Open an app resource file
82+
83+
| Param | Type |
84+
| ------------- | ----------------------------------------------------------------------------- |
85+
| **`options`** | <code><a href="#openfromresourcesoptions">OpenFromResourcesOptions</a></code> |
86+
87+
**Since:** 1.0.0
88+
89+
--------------------
90+
91+
92+
### openDocumentFromUrl(...)
93+
94+
```typescript
95+
openDocumentFromUrl(options: OpenFromUrlOptions) => Promise<void>
96+
```
97+
98+
Open a file from a remote url
99+
100+
| Param | Type |
101+
| ------------- | ----------------------------------------------------------------- |
102+
| **`options`** | <code><a href="#openfromurloptions">OpenFromUrlOptions</a></code> |
103+
104+
**Since:** 1.0.0
105+
106+
--------------------
107+
108+
109+
### previewMediaContentFromLocalPath(...)
17110

18111
```typescript
19-
echo(options: { value: string; }) => Promise<{ value: string; }>
112+
previewMediaContentFromLocalPath(options: PreviewMediaFromLocalPathOptions) => Promise<void>
20113
```
21114

22-
| Param | Type |
23-
| ------------- | ------------------------------- |
24-
| **`options`** | <code>{ value: string; }</code> |
115+
Preview a media file (namely, video) stored in the local file system.
116+
Only implemented in iOS. Android defaults to `openDocumentFromLocalPath`.
25117

26-
**Returns:** <code>Promise&lt;{ value: string; }&gt;</code>
118+
| Param | Type |
119+
| ------------- | ----------------------------------------------------------------------------- |
120+
| **`options`** | <code><a href="#openfromlocalpathoptions">OpenFromLocalPathOptions</a></code> |
121+
122+
**Since:** 1.0.0
123+
124+
--------------------
125+
126+
127+
### previewMediaContentFromResources(...)
128+
129+
```typescript
130+
previewMediaContentFromResources(options: PreviewMediaFromResourcesOptions) => Promise<void>
131+
```
132+
133+
Preview a media file (namely, video) from the app's resources.
134+
Only implemented in iOS. Android defaults to `openDocumentFromResources`.
135+
136+
| Param | Type |
137+
| ------------- | ----------------------------------------------------------------------------- |
138+
| **`options`** | <code><a href="#openfromresourcesoptions">OpenFromResourcesOptions</a></code> |
139+
140+
**Since:** 1.0.0
27141

28142
--------------------
29143

144+
145+
### previewMediaContentFromUrl(...)
146+
147+
```typescript
148+
previewMediaContentFromUrl(options: PreviewMediaFromUrlOptions) => Promise<void>
149+
```
150+
151+
Preview a media file (namely, video) from a remote url.
152+
Only implemented in iOS. Android defaults to `openDocumentFromUrl`.
153+
154+
| Param | Type |
155+
| ------------- | ----------------------------------------------------------------- |
156+
| **`options`** | <code><a href="#openfromurloptions">OpenFromUrlOptions</a></code> |
157+
158+
**Since:** 1.0.0
159+
160+
--------------------
161+
162+
163+
### Interfaces
164+
165+
166+
#### OpenFromLocalPathOptions
167+
168+
| Prop | Type | Description | Since |
169+
| ---------- | ------------------- | ------------------------------------------ | ----- |
170+
| **`path`** | <code>string</code> | The full absolute path to the file to open | 1.0.0 |
171+
172+
173+
#### OpenFromResourcesOptions
174+
175+
| Prop | Type | Description | Since |
176+
| ---------- | ------------------- | ---------------------------------------------- | ----- |
177+
| **`path`** | <code>string</code> | The relative path to the resource file to open | 1.0.0 |
178+
179+
180+
#### OpenFromUrlOptions
181+
182+
| Prop | Type | Description | Since |
183+
| --------- | ------------------- | ------------------------------------------- | ----- |
184+
| **`url`** | <code>string</code> | The remote url pointing to the file to open | 1.0.0 |
185+
186+
187+
### Type Aliases
188+
189+
190+
#### PreviewMediaFromLocalPathOptions
191+
192+
<code><a href="#openfromlocalpathoptions">OpenFromLocalPathOptions</a></code>
193+
194+
195+
#### PreviewMediaFromResourcesOptions
196+
197+
<code><a href="#openfromresourcesoptions">OpenFromResourcesOptions</a></code>
198+
199+
200+
#### PreviewMediaFromUrlOptions
201+
202+
<code><a href="#openfromurloptions">OpenFromUrlOptions</a></code>
203+
30204
</docgen-api>
31205

32206
### Errors
33207

208+
The plugin returns the following errors with specific codes on native Android and iOS:
34209

210+
| Error code | Platform(s) | Message |
211+
|-------------------|------------------|------------------------------|
212+
| OS-PLUG-FLVW-0004 | Android, iOS | The file you are trying to open does not exist. |
213+
| OS-PLUG-FLVW-0005 | Android, iOS | The URL you are trying to open is malformed. |
214+
| OS-PLUG-FLVW-0006 | Android, iOS | Path of the file to open is either null or empty. |
215+
| OS-PLUG-FLVW-0007 | Android, iOS | URL to open is either null or empty. |
216+
| OS-PLUG-FLVW-0008 | Android, iOS | Could not open the file. |
217+
| OS-PLUG-FLVW-0009 | Android, iOS | Invalid parameters. |
218+
| OS-PLUG-FLVW-0010 | Android | There is no app to open this file. |
219+
| OS-PLUG-FLVW-0011 | iOS | Cordova / Capacitor bridge isn’t initialized. |
220+
| OS-PLUG-FLVW-0012 | iOS | The download failed. |
221+
| OS-PLUG-FLVW-0013 | iOS | The file has no extension. |

0 commit comments

Comments
 (0)