Open URL/File
Opens, in the client device, the URL or file that is specified in the action. A URL is opened in the client's default Internet browser. A file on the client device is opened in the client's default app for that file type. In the action's configuration options, select the Open URL or Open File in external app radio button and then enter details of the URL or file to open.
In both cases, an option is available for web clients to open the URL in the current tab (or, alternatively, in a new tab of the browser); see screenshots below.
Open URL
In the XPath expression dialog of the Open URL action, if you select Open URL, then you can enter an expression that either: (i) evaluates to a string that is the URL to be opened (first screenshot below), (ii) evaluates to a string that constructs a data url (second screenshot below), or (iii) evaluates to a sequence of strings that constructs a command line instruction (for use in simulations in MobileTogether Designer only).
Data URLs
Data URLs enable you to open binary files directly in a new tab of the web client's browser. Note that these URLs can be accessed in web clients only. The syntax of a data URL is as follows:
data:[<mediatype>][;base64],<data>
A data URL consists of four parts (colored differently above). The data: part is a fixed prefix. The <mediatype> part is a MIME type. The ;base64 token is optional; if used, it indicates that the <data> part must be read as Base64-encoded data; if omitted, the <data> part will be read as text. The Base64-encoded data can be read dynamically from a node in a page source (for an example, see below).
Example:
data:application/pdf;base64,<SomeBinaryData-SuchAsInThe-$BINARIES/PDF-Node>
In an XPath expression, a data URL that reads Base64-encoded data from a node can be entered as shown in the screenshot below. In this expression, the Base64-encoded data is contained in the $BINARIES/PDF node.
| Note: | Base64-encoded data in a node can also be saved to file with the Save to Binary File action, and the file can then be opened. The Open Data URL action, on the other hand, opens the file with one click only. |
Sequence of strings for a command line instruction
The XPath expression for Open URL can also be constructed so that it evaluates to a command line instruction. In this case, the XPath expression must evaluate to a sequence of strings, where the first string would be the filepath to the executable. The parameters of the command line instruction can then be specified in: (i) a second string of the sequence, where each space-separated token is a command line parameter; (ii) subsequent strings of the sequence, where every subsequent string corresponds to one command line parameter; or (iii) a combination of the previous two patterns (that is, where there is more than one subsequent string, with each of these corresponding to one or more command line parameters).
| Note: | The parameters would have to be entered in the correct order. |
| Note: | The option for constructing a command line instruction can only be used in a simulation in MobileTogether Designer. It will have no effect when run on a client. |
Examples:
The two examples below call Altova DiffDog in order to compare two XML files. The first XPath expression is a sequence of two strings. The second is a sequence of three strings. In both cases, the command line instruction that is constructed will be the same.
("C:\Program Files\Altova\DiffDog2021\DiffDog.exe",
"C:\TestFiles\Colors2.xml C:\TestFiles\Colors3.xml")
("C:\Program Files\Altova\DiffDog2021\DiffDog.exe",
"C:\TestFiles\Colors2.xml",
"C:\TestFiles\Colors3.xml")
| Note: | If a filepath contains a space, the filepath should be enclosed in quotes (single or double, as required). |
Open file in external app
This action opens a file that is located on the client device. You can specify the file directly in the design, or you can let the end-user select the file. The file will be opened in the device's default app for the selected file's filetype. If the client is a web client, the file will be opened in a browser tab; an option is available to select either the current tab or a new tab. Note that, in web clients, file selection by the end-user is not available.
When you click the Open File action's Edit button, an Open dialog appears (screenshot below). Select the options that apply.
File location is stored in design
To directly specify (in the design) the device file to open, select Define file path below (see next screenshot). Enter an absolute or relative file path, or an XPath expression that evaluates to such a file path. If you enter a relative path, then this path is resolved relative to the base directory you specify for that device type (see list and screenshot below).
•Android: Select the Android device-directory from the dropdown list. If you select Default, which is the default selection, the MobileTogether app's sandbox directory is selected. Note, however, that, unless the Android device is rooted, no other app (besides MobileTogether) will be able to access the MobileTogether sandbox directory. So, trying to open a file in the MobileTogether sandbox with another app could fail.
•Windows RT: Select the Windows Phone or Windows RT device folder from the dropdown list. If you select Default, which is the default selection, the MobileTogether app's sandbox directory is selected.
•iOS: MobileTogether creates two directories on the user's device: (i) a Backed-up directory for files that are backed up by the operating system and will be available at later times, for example, after a restore. This directory is intended for files that are important for the user and that should not be lost; (ii) a Non-backed-up directory for files that do not need to be backed up, or if faster buffering is needed for playback. Select Backed-up directory or Non-backed-up directory as required.
•Web browser: No selection is available. Relative paths are resolved within the context of the browser's sandbox.
User selects device file
To let the end user select a file on the mobile device, select Let user select file on device (see screenshot below). When the action is processed at runtime, the end user can browse for, or enter the name of, a device file to open.
This option provides the following options:
•Optional File Filter: The browse dialog that is opened on the client device will filter the file types to be opened so that only those file extensions that you have defined here are allowed. You can enter: (i) a comma-separated or semicolon-separated list of extensions (for example: txt,html;xml), or (ii) an XPath expression that returns a sequence of string items, where each string item is a file type extension (for example, here is one sequence containing three string items: 'txt','html,'xml').
•Web Message Box: Before the File Open dialog is opened on the client device, a message box is displayed. You can enter a message to override the default text of this message box. Enter the text of the message directly, or via an XPath expression.
Error processing
The On Error option lets you define what should be done if an error occurs. Since the error handling can be precisely defined for this action, errors on such actions (that provide error handling) are treated as warnings—and not errors. The advantage is that you do not need to check errors on actions for which error handling has already been defined. The following error handling options are available:
•Abort Script: After an error occurs, all subsequent actions of the triggered event are terminated. This is the default action if an error occurs. If you wish to continue despite an error, select either the Continue or Throw option.
•Continue: Actions are not terminated. Instead, you can select what to do in either event: when there is no error (On Success), or when there is an error (On Error). For example, you might want to display a message box saying whether a page load was successful or not.
•Throw: If an error is detected, this option throws an exception that is stored in the Try/Catch action's variable. The Catch part of the Try/Catch action is used to specify what action to take if an error occurs. If no error occurs, then the next action is processed. See the section Try/Catch action for details.
An error is registered only if the file does not exist. If the file exists, a success is registered—even if the file could not be opened by any device app.
MobileTogether extension functions
MobileTogether provides a range of XPath extension functions that have been specifically created for use in MobileTogether designs. Some functions can be particularly useful with specific actions. For example, mt-available-languages() returns the languages in which the solution is available and could, for example, be used with the Message Box action. If a function is especially relevant to this action, it is listed below. For a full list of extension functions and their descriptions, see the topic MobileTogether Extension Functions.
mt-extract-file-extension()
mt-extract-file-name()