PhoneGap - Open File with Native Application

Description

This action allows you to open a file on a mobile device using the associated native application.

Discussion

This action allows you to open a file using a native application on a mobile device in a Cordova application. To use this Action Javascript, you must load the Cordova Open plugin.

This actions allows you to:

  • Open a file that is already present in the file system of the mobile device.
  • Open a file that is remote.
  • Open a file that is dynamically created by making an Ajax callback to the server.
  • Open a PDF report that is created by making an Ajax callback to the server to run a report and save the report output as a PDF file.
You can only use this action in a Cordova application. The Cordova application must load the Cordova Open plugin.

When you select the PhoneGap - Open File with Native Application action in Action Javascript, the following dialog is shown:

images/nativeopenergenie1.jpg

The following properties are used tos specify the location of the file to open:

Property
Description
File is remote

Specify if you want to open a local file, or a remote file (i.e. a file that is on a remote server)

Filesystem part

The part of the device filesystem where the file is stored. You can specify a Javascript function to return the filesystem part by prefixing the name of the Javascript function with javascript:, For example javascript:getFileSystemPart.

Filename

The name of the file you want to open. This can include a relative path if the file is stored in a sub-directory. E.g. PDF/mypdffile.pdf. You can also specify a Javascript function to return the filename by prefixing the name of the Javascript function with javascript:, For example javascript:getFileName.

If you specify that the file is remote, you must specify the File URL.

images/cordovaaction2.gif
Property
Description
File URL

The URL of the file you want to open. For example: http://alphafiles.s3.amazonaws.com/pdffile1.pdf. If the file is stored in the webroot of the Application Server, you can specify a relative filename. For example: pdffile1.pdf. You can specify a Javascript function to return the URL by prefixing the name of the Javascript function with javascript:, For example javascript:getFileURL.

Make Ajax callback to get the file to view

Specify if an Ajax callback should be made to dynamically create the file that you want to view on the mobile device.

If you specify that you want to make an Ajax callback to get the file to open, you must specify the Ajax callback type.

images/codovaopen3.gif
Property
Description
Ajax callback type

Can either be UserDefined or Report. Choose UserDefined if you want to create your own Xbasic function to handle the callback. Choose Report if you want to run a Report that you have defined in your web project and save the report as a PDF file.

Xbasic function

The name of the Xbasic function that will handle the Ajax callback. In addition to generating the file you want to view on the mobile device, your Xbasic function must return Javascript to set these variables:

{dialog.object}.__filenameNativeViewer

The URL of the file you want to view.

{dialog.object}.__filenameFriendlyNativeViewer

The friendly name for the file that will be displayed in the title bar of the Viewer app.

To see an example of how these variables should be set by your Xbasic function, click the smart field for the Xbasic function property. Then click the Show function prototype button.

If you set the Ajax callback type to Report, you must specify which report you want to run.

images/cordovaopen4.gif
Property
Description
Report definition

When you click the smart field for this property a genie opens up (see below) where you can define which report to run.

Friendly name

The name shown in the title bar of the Native Opener. Name can be statically defined at design-time or dynamically computed using a JavaScript function using the syntax shown below.

javascript:yourfunctionname

Replace "yourfunctionname" with the name of your JavaScript function (function names are case-sensitive.) The JavaScript function must return a URL encoded value to use for the friendly name.

If no name is specified, a default name is computed based on the report name.

onComplete Javascript

The name of a Javascript function to run after the report has been generated. See below for an example of how this property can be used.

Alpha Anywhere will automatically send the following Javascript to the client once the report has been created:

{dialog.object}.hideWaitMessage();

This is useful because if you displayed a wait message when invoking the action to save a report as a PDF file, the wait message will automatically be closed once the report has been generated. You do not have to specify an onComplete Javascript property solely for the purpose of hiding a wait message.

Report Definition Genie

When you click the smart field for the Report definition property, the following dialog is shown where you can specify the name of the report to run and other properties of the report, such as the filter, and order, PDF options (such as whether the PDF file should have a watermark, etc.) and argument bindings.

images/cordovaopen_reportgenie.jpg

The filter you define for the report in this dialog is in addition to any filter defined in the report definition itself.

When defining a filter, it is common to use arguments in the filter rather than literal values. For example:

Country = :whatcoutry

rather than

Country = '{country}'

where {country} is the value in a control called Country on the UX component.

To create an argument to use in a report filter click on the Define Arguments button shown in the above image and then bind the argument to a value (either a static value, or a value in a UX control) in the Set Argument Values section of the dialog.

Understanding the onComplete Javascript Property

When you set the Ajax Callback type to Report, the onComplete Javascript property allows you to define the name of a Javascript function that will be called after the report has been generated on the server.

Your function will take a single parameter as its input. This parameter is an object with these properties:

Property
Description
localFilename

The file name in the filesystem on the device where the report will be saved after it is downloaded to the mobile device.

reportName

The name of the report that was printed

fileSystem

The filesystem part where the report PDF file will be stored. e.g. saved, private, public, persistent, temp.

folder

The name of the folder in which the report PDF file will be stored.

A common use case for this function is to store the name of the report and its associated properties (such as filesystem part, filename, etc), in a List control so that the user can quickly view a previously viewed report by simply viewing the file for that report (which is stored on the device after it is viewed for the first time). This allows the user to view reports even when there is no connection.

For example, the following function would store the report information in a List control called previouslyViewedReports (assume that the List control has columns named filename, reportname, fspart and folder):

function afterReportGenerated(obj) {
    var l = {dialog.object}.getControl('previouslyViewedReports');
    var _d = [
        {
            filename: obj.localFilename,
            reportname: obj.reportName,
            fspart: obj.fileSystem,
            folder: obj.folder
        }
    ];
    l.appendRows(_d);
}

Limitations

Cordova Applications Only

See Also