@angelengineering/filepicker

Nativescript filepicker

This file picker plugin exports function filePicker() that supports both single and multiple selection (for iOS, multiple selection feature depends on OS version) using only native picker approaches.

For iOS, filePicker() uses UIDocumentPicker to allow selection from publicly available files that can be accessed via iOS Files app. When selecting from Files, UIDocumentPicker supports multiple selections.

iOS also has access to the galleryPicker() function which selects from the iOS Photos Gallery. This picker uses UIImagePicker for iOS 13 and below, which only supports single selections. PHPicker is used for iOS 14+ which does support multiple selections from the Photos Gallery. This picker does require user permission before allowing access to media on iOS.

For Android, filePicker() uses Intents to open the stock file picker. For Android 6 (API 23) and above the permissions to read file storage should be explicitly required in AndroidManifest. See demo for implementation details. Note: galleryPicker() will just call filePicker() internally.

ns plugin add @angelengineering/filepicker

Usage

The best way to explore the usage of the plugin is to inspect the demo app in the plugin repository. In apps/demo folder you can find the usage of the plugin for TypeScript non-Angular application. Refer to apps/demo/src/plugin-demos/filepicker.ts.

In short here are the steps:

Import the plugin

TypeScript

import { Filepicker, MediaType } from '@angelengineering/filepicker';

Create filepicker instance

TypeScript

let picker = new Filepicker();

Decide which types of files to include, and whether single or multiple selections allowed

    try {
      pickedFiles = await picker.filePicker(MediaType.IMAGE + MediaType.VIDEO + MediaType.AUDIO, true);
    } catch (err) {
      if (err) alert(err?.message);
    } finally {
      this.handleFiles(pickedFiles);
    }

NOTE: To request permissions in the demo app, we use perms plugin. While this is not required for all OS versions and corresponding pickers, just to be safe you should request it so user is aware.

NOTE: Be sure to have permissions add the following lines in AndroidManifest.xml.

<manifest ... >
  <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>

  <application android:requestLegacyExternalStorage="true" ... >
    ...
  </application>
</manifest>

NOTE: Using the plugin on iOS to select from the Photos gallery with galleryPicker() requires user to grant photo library permission first in order to access the selected image, otherwise it will return without any files. Your app might be rejected from the Apple App Store if you do not provide a description about why you need this permission. The default message "Requires access to photo library." might not be enough for the App Store reviewers. You can customize it by editing the app/App_Resources/iOS/Info.plist file in your app and adding the following key:

<key>NSPhotoLibraryUsageDescription</key>
<string>Requires access to photo library to upload media.</string>

NOTE: if you do use the perms plugin, make sure to read their README.md first, as using this plugin in production apps will require you to add all iOS Info.plist permission strings to avoid being rejected by automatic processing since the plugin includes code for all permission types.

Supported Picker File Types

MediaType {
  IMAGE,
  AUDIO,
  VIDEO,
  ARCHIVE,
  DOCUMENT,
  ALL     =>   (IMAGE | AUDIO | VIDEO | ARCHIVE | DOCUMENT )
}

Android

The Android stock file picker also supports selecting files from Google Photos and Google Drive if you have an account signed in on the Android device.

iOS

The iOS pickers also support selecting files from an associated iCloud account if the user has signed in on the device. Note that for a production application, you'll need to add the iCloud capability to your iOS application, and register that entitlement via the Apple Developer site for that package id. After that, update the relevant keys as shown in the demo application's Info.plist.

Additional Utils

This plugin also exports a function getFreeMBs which a dev can use to check free space on the current device/app's cache folder which is where picked files get copied to. This is useful when working with larger video files to ensure you have enough free space before picking/copying the video file for use in your app.

License

Apache License Version 2.0