Native file documents

Category: Modules
Subcategory: All

Overview

View file documents on the device. Access the file system of the native device. Share documents to other apps on the device.

Documentation

Demo url

Description

Access the file system of the native device. View file documents on the device, as temporary solution until the Mendix platform supports this.

Due to the nature of this module, it comes with a disclaimer and warning, by using this module you accept and agree to it:

This module provides a convenient way for viewing files and images. However, it is an advanced, highly technical module! You need to create a custom build to use it, it does not work in the Make It Native app!

The module is free to use, as is, and we will update it regularly for new Mendix releases.

Unfortunately, we cannot provide extended support on using this module. The functions are documented and a sample project will be available too.

Be advised that incorrect usage of the JavaScript actions in this module can cause issues in your app, like deleting files that you did not create yourself. We do not accept any liability or responsibility!

If you are interested we are of course willing to provide assistance, you may contact use here: https://developer.mendixcloud.com/link/partnerprofile/4808

 

Since you’re still reading, now comes the good stuff!

Typical usage scenario

To work with file documents on the native device

Features and limitations

JavaScript actions:

  • copyFile
  • deleteItem
  • downloadFile
  • exists
  • getFileDocumentUrl
  • getFullPath
  • IsNativeFileSystemAvailable
  • mkdir
  • openDocumentPicker
  • readDir
  • saveToMendixFileDocument
  • shareOpen
  • stopDownload
  • viewFile
  • writeFile

Each action is documented in the module. Most have a writeToLog parameter, which controls whether the log details are written to NativeActionLog. Snippet Snippet_SyncDebug_NativeActionLog shows the log on the native app.

Just make sure to call IsNativeFileSystemAvailable at least once in your app. This is good practice anyway, it also allows your app to fail gracefully when a developer attempts to use the functionality in the Make It Native app.

Viewing file documents and images

It is possible to synchronize FileDocument entity types to the device. However, currently the viewFile JS action does not work with them because the file on the device has lost the file extension. The extension is necessary for the library to work correctly.

To come around this issue, nanoflow SUB_ViewDocument is available. It can be called with any specialization of FileDocument and will copy the file on the device to its original name and start the viewer.

Supported file types are PDF, JPG, PNG. Most Office types are supported too but on Android these open in the specific app.

Unsupported file types are treated differently on each platform: On Android nothing will happen at all on older versions, but recent Android versions throw an error when file cannot be viewed. On iOS, the viewer will open but not show any contents.

Cleanup of viewer temp files The viewFile action cannot tell if and when the viewer was closed. So there will be temporary copies on the device nanoflow SUB_DeleteFileViewerTempDirectory deletes the temporary stuff so be sure to call that flow regularly

Document picking on the device

With JavaScript action openDocumentPicker the user can select documents to be used in the Mendix app. The result has a uri, which can be saved into a Mendix FileDocument using JavaScript action saveToMendixFileDocument. The sample project has an  example of this.

Sharing content

With JavaScript action shareOpen the user can share content outside the app. Note that the share JavaScript action in NanoflowCommons allows you to share single texts, so if that is your requirement, no need for anything more. With shareOpen, you can share documents as well. The sample project has an  example of this.

Limitation: Some apps handle the content passed to them better than others. For example, the iOS default mail app will accept subject, body message and one or more images or documents in one shareOpen call. WhatsApp on iOS will ignore any documents as soon as texts are passed as well. Currenly the only way around this is to share any images or documents in a separate shareOpen call. Be sure to test on both platforms to check whether the result matches the requirements of your app!

Dependencies

Installation

Download the Mendix appstore module.

Make sure that the NativeActionLog synchronization setting is set to 'Nothing’. (Native navigation profile, Sync configuration button)

Create a native build using the native builder UI. You need at least version 1.0.78 and allow it to update the native template if it prompts you for the update. The additional native module dependencies will be included automatically during the native build for Mx9.

When building for Mx8, use npm install to include the native dependencies react-native-fs, react-native-file-viewer, react-native-share and react-native-document-picker. Check the native dependency files in javascriptsource\nativefiledocuments\actions\ for the right version!

Also run pod install in the ios folder again for iOS builds.

Android specific

You need to add a query to the Android Manifest for Android 11 and up:

    <queries>
        <intent>
            <action android:name="android.intent.action.VIEW" />
            <data android:mimeType="*/*" />
        </intent>
    </queries>

Place it directly before the close tag, see screenshot.

Releases

Version: 3.0.0
Framework Version: 9.4.0
Release Notes: Mendix 9.4, Atlas 3. Dependency on NanoflowCommonsITvisors removed. For Android 11, you need to edit the Android manifest file, see docs!
Version: 2.3.0
Framework Version: 8.18.3
Release Notes: Added shareOpen action to share documents (and text) to other apps Updated native dependency versions. -> Mx8 devs: update your native app build!!! Split the native dependency files for key JavaScript actions
Version: 2.2.1
Framework Version: 8.18.3
Release Notes: Recent Android versions throw an error when file cannot be viewed
Version: 2.2.0
Framework Version: 8.18.3
Release Notes: Added native document picker
Version: 2.1.0
Framework Version: 8.18.2
Release Notes: Added support for downloading files directly, thanks to Arjen Lammers! Mendix 8.18.2. Also supports Mx9 native dependency features.