ion-android-fileviewer

The ion-android-fileviewer is a library built using Kotlin that uses Android Intents to view files.

Use the IONFLVWController class to open files, from local paths, app's assets, and remote URL's.

Index

• Motivation
• Usage
• Methods
  • Open document from local file path
  • Open document from a remote URL
  • Open document from app's assets
• Errors
• Contributing
• License
• Support

Motivation

This library is used by File Viewer Plugins - for both OutSystems' Cordova Plugin and Ionic's Capacitor Plugin.

Usage

In your app-level gradle file, import the ion-android-fileviewer library like so:

dependencies {
    implementation("io.ionic.libs:ionfileviewer-android:1.0.0")
}

Methods

This section details the methods provided by the IONFLVWController:

Open document from local file path

fun openDocumentFromLocalPath(
    activity: Activity,
    filePath: String
): Result<Unit>

The method is composed of the following input parameters:

• activity: the Activity from the app using the library to use when for opening the file in another app.
• filePath: String with the full path to the file.

The method returns a Result, that is either success (no data is returned) if file was opened, or an exception that should be handled by the caller app.

Open document from a remote URL

fun openDocumentFromUrl(
    activity: Activity,
    url: String
): Result<Unit>

The method is composed of the following input parameters:

• activity: the Activity from the app using the library to use when for opening the url in another app.
• url: String with the url to open.

The method returns a Result, that is either success (no data is returned) if url was opened, or an exception that should be handled by the caller app.

Open document from app's assets

@WorkerThread
fun openDocumentFromResources(
    activity: Activity,
    assetPath: String
): Result<Unit>

The method is composed of the following input parameters:

• activity: the Activity from the app using the library to use when for opening the file in another app.
• assetPath: String with the relative path to the file inside the assets folder.

The method returns a Result, that is either success (no data is returned) if file was opened, or an exception that should be handled by the caller app.

Unlike the other methods, this cannot be called from the main thread, because it contains I/O operations that could freeze the UI. You may create a thread using Kotlin's thread function, or use coroutines, as exemplified below:

val coroutineScope = CoroutineScope(Dispatchers.IO)
val fileViewerController = IONFLVWController()
coroutineScope.launch {
    fileViewerController.openDocumentFromResources(activity, assetPath)
        .onSuccess {
            // handle file open successfully here
        }
        .onError {
            // handle errors here
        }
}

Errors

The exceptions returned by the plugin method are all of type IONFLVWException.

Some exceptions may have a cause in case it was thrown outside the controller (e.g. by Android OS).

Contributing

1. Fork the repository (Unselect "Copy only main branch")
2. Checkout development branch.
3. Create your feature branch (git checkout -b feature/amazing-feature)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request to development.

License

ion-android-fileviewer is available under the MIT license. See the LICENSE file for more info.

Support

• Report issues on our Issue Tracker