Altova MobileTogether Designer

The Print To action (screenshot below) uses Altova StyleVision Server (version 2017sp1 or later) to generate a PDF, Word, or RTF output document. The mechanism works as follows: XML data in one of the design's page source nodes or in an external XML file is processed with a PXF file, which is essentially an XSLT stylesheet. Altova StyleVision Server is used to carry out this XSLT transformation. In order for the Print To action to be carried out, the StyleVision Server application, which is available for download at the Altova website, must be installed on the same computer as MobileTogether Designer (for local simulation) and as MobileTogether Server (for server simulations and deployed use).

Note about PXF files and StyleVision Server

•A Portable XML Form (PXF) file is a file format that has been specially developed by Altova to package XSLT stylesheets for multiple outputs into one file. The various XSLT stylesheets are generated from a single design created in Altova StyleVision.

•In the design, you can define parameters, which are then also defined in the XSLT stylesheets contained in the PXF file. At runtime, values can be passed to these parameters in the stylesheets.

•StyleVision Server is a lightweight command-line application that is used to run XSLT transformations that generate output in various formats.

•For more information about the PXF format, see the Altova StyleVision documentation. For more information about StyleVision Server, see the Altova StyleVision Server documentation.

The Print To action takes the following options:

PDF/Word/RTF

Specifies the type of print output document: .pdf, .docx, or .rtf. You can also use an XPath expression to select the output. The result of the evaluation should be one of the following strings: "PDF", "Word", or "RTF" (case-insensitive). Using an XPath evaluation enables you to make the selection of print format conditional.

Source

You can select either: (i) an XML node of one of the design's page sources, or (ii) an external XML file, which can be on the client device or on the server.

Source Node

If you choose Node as your source, then enter an XPath expression to select the node you want to use as source data for the output document. The node you select will be entered as the value of this option, and can be changed subsequently.

Source File

If you choose File as your source, the path to the file you select will be entered as the value of the Source File option. You can also add a filepath (or modify an already entered filepath) by clicking the Edit button of the Source File option. A dialog appears in which you can select a server file or client file. See the section File locations below for details of the available options. On selecting a file that is defined to reside on the server, you are asked whether the file should be deployed to the server or not. If the file is not deployed, it must be stored in the solution's working directory (or a descendant directory); in this case, the path that you enter for this (Source File) option must be correctly set so that the solution correctly accesses the source file at runtime.

PXF File

The PXF file is the stylesheet container file that StyleVision Server uses to generate the output document. Select the PXF file using one of the methods described for server locations in the File locations section below. If you do not deploy the PXF file, make sure that you save it in the solution's working directory (or a descendant directory); in this case, the path that you enter for this (Source File) option must be correctly set so that it correctly accesses the PXF file at runtime..

Target File

Specifies the name of the output file and its location (on server or client). Use any one of the ways described in the section File locations below to specify the file's location.

Parameters

At runtime, parameter values can be passed to the stylesheets in the PXF file. This option enables you to specify multiple parameter values. Click the Add Parameter icon to add a parameter entry. Then enter the parameter's name and value as XPath expressions. In the screenshot above, for example, the first parameter has a name:value pair of "year":"2017". The second parameter takes its value from the node $XML2/doc/version. You can add as many parameter values as you like.

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.

File locations

When you click the Additional Dialog button of the Source File, PXF File, and Target File options, a Specify File dialog appears in which you can specify the file to load or save, respectively.

•Source file: Selects an XML data file that is located on the server or client. If you select a file on a local or network machine, make sure that you either: (i) deploy the file with the design to the server, or (ii) store the file to the solution's working directory on the server (or a descendant directory).

•PXF file: Selects a PXF file that is located on the server.  If you select a file on a local or network machine, make sure that you either: (i) deploy the file with the design to the server, or (ii) store the file to the solution's working directory on the server (or a descendant directory). A client-based PXF file cannot be specified.

•Target file: Generates the output to a server or client location.

The available options in the Specify File dialog depends on whether the file is being loaded (Source File and PXF File) or saved (Target File).

File is located on server

The term server location refers to the location of the file at runtime. When you select a file to load, you can select it from any location on your network. However, in order to make the file accessible at runtime, you must either: (i) deploy the file to the server, or (ii) save it to the solution's working directory on the server. To specify the file to load, you can either browse for its location (Absolute/Relative Path) or specify the file via a global resource (File Alias or Folder Alias). In the dialog, select the options you want.

•Absolute/Relative Path: You can enter a path, browse for a file, or enter an XPath expression that generates the path to the file. Use the Reset button to remove the current entry. The path can be relative to the design file, or absolute. If the file is deployed to the server along with the design file, then the relative/absolute path specified in the dialog will be used internally (in the server's database) to access the file. If the file is not deployed, then it must be stored in a directory on the server. In this case: (i) if a relative path is selected in the Load From or Save/Specify File dialog, then, at runtime, this relative path will be resolved on the server with reference to the Working Directory (defined in the MobileTogether Server settings); (ii) if the path in the Load From or Save/Specify File dialog is absolute, the file's containing folder on the server must be a descendant of the Working Directory. See the section Location of Project Files for details. You can also choose whether to allow untrusted SSL connections or not, when accessing or saving the file. If the Absolute/Relative Path field is in a dialog to save a file—and not to load a file—you can optionally specify a default file extension; this extension will be used if none is specified with the file name.

•Automatically create subfolders on file save: If intermediate folders in the file path are missing on the server, they will be created when the file is saved. This option is relevant only when saving; it is absent where the action is restricted to file loading.

•Allow untrusted SSL connections: A certificate associated with a URL is considered untrusted if it isn’t signed by a trusted root certificate or if it can’t link to a trusted root certificate. If the certificate is signed by a major certificate authority, it just means that one of the chain certificates in between yours and the root is not installed on the web server. If a trusted certificate is expected (for example, because the HTTPS protocol is specified), then selecting this option enables connections also with URLs that have an untrusted certificate.

•Global Resource File Alias: Select a file alias from the file aliases available in the combo box. The available file aliases will be those currently defined in the Global Resources Definitions file. Each file alias maps to different file resources according to the currently active configuration in MobileTogether Designer (selected via the command Tools | Active Configuration). See the section Altova Global Resources for details.

•Global Resource Folder Alias with path fragment: Select a folder alias from the folder aliases available in the combo box (see screenshot below).
 

 

The available folder aliases will be those currently defined in the Global Resources Definitions file. Each folder alias maps to different folder resources according to the currently active configuration in MobileTogether Designer (selected via the command Tools | Active Configuration). The path fragment specifies the rest of the path to the file resource. See the section Altova Global Resources for details.

File is located on client

If the file is located on the client, specify the path to it by entering/selecting the location, or by constructing the path with an XPath expression. Use the Reset button to remove the current entry.

The file to load/save can be specified by you, the designer, or it can be specified by the end user. If you specify the file, then this information will be stored in the solution, and the file will be loaded/saved when the action is triggered. If you choose to let the end user select the file to be loaded/saved, then, when the action is triggered, a browse dialog is opened on the client device and the end user can enter/select the file to load/save.

Filename is defined below (by the designer of the solution)

•Default file extension for file saving: When saving files, you can optionally specify a default file extension; this extension will be used if none is specified with the file name.

•Automatically create subfolders on file save: If intermediate folders in the file path are missing on the client, they will be created when the file is saved. This option is relevant only when saving; it is absent if the action is a file loading action.

•Device dependent directories: Select the device directory from the dropdown list. On Windows Phone/RT and iOS, the allowed directories are pre-determined. On Android devices, in addition to the directories in the dropdown list of the Android combo box, you can enter any folder you like. On Android and Windows Phone/RT, if you select Default, which is the default selection, the MobileTogether app's sandbox directory is selected. On iOS devices, MobileTogether creates two directories: (i) a Backed-up directory for files that are saved to the iCloud, and which can then be re-downloaded; (ii) a Non-backed-up directory for files that do not need to be backed up. Select Backed-up directory or Non-backed-up directory as required. In web browsers, files are located relative to the browser's sandbox.

•File locations for simulations: Since files located on the client will not be available during simulations, you can specify a folder that will stand in for the client folder during simulations. Files within this stand-in folder must, of course, have the same names as the files specified in the design. This folder is specified in the Simulation tab of the Options dialog (Tools | Options).

Note:  On web clients, files are stored temporarily on the server. They are deleted from there when the server session ends. A server session ends after a specified period of inactivity; this period is defined in the Sessions setting in the Misc pane of the Server Settings tab (see the MobileTogether Server user manual).

Filename is defined by the end user (on the client device)

•Default file extension for file saving: When saving files, you can optionally specify a default file extension; this extension will be used if none is specified with the file name.

•Optional File Filter: The browse dialog that is opened on the client device will filter the file types to be loaded/saved so that only those file extensions that you have defined 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').

•Optional Default File: You can enter a default filename, either directly or via an XPath expression, to guide the end user.

•Web Message Box: Before the File Open/Save dialog is opened, a message box is displayed. You can enter text directly or via an XPath expression to override the default text of the message box.

•Automatically create subfolders on file save: If intermediate folders in the file path are missing on the client, they will be created when the file is saved. This option is relevant only when saving; it is absent if the action is a file loading action.

Note:  On iOS devices, letting the user select the file on the device works only as an import/export from/to the iCloud; users are not allowed to browse the backed-up folder or non-backed-up folder.

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.