Altova MobileTogether Designer

Enables the addition of elements and attributes relative to the selected node. Insert adds the node before the selected node. Append adds the node after the last node of that type. If you wish to add a node immediately after the selected node, go to the following node and use the Insert command.

Deletes the selected page source, respectively, from the current page and from all pages of the project.

To reduce the amount of data transmitted over the mobile data network—which improves the performance of any mobile solution—MobileTogether lets you specify whether data from the selected page source is transmitted to client devices and/or kept on the server. For example, if a certain data set is only necessary to display a graph, then that data can be kept on the server. The image of the graph (say in PNG format) will be rendered by the server and transmitted to the client without the underlying data being transferred over the mobile network. For large data sets this produces a significant performance boost.

This command specifies whether data in the tree is stored on the server only, the client only, or shared by both. Note that if data is stored on the server, then it cannot be defined as persistent. See the Persist data on client command below.

A toggle command which specifies that data in the tree is read only. A read-only data tree is used to provide data for display and calculations. It cannot be used to hold data that needs to be edited.

A toggle command that makes a tree a persistent tree. Any number of trees can be defined as persistent. When a tree is defined as persistent, data in it is retained on the client device after the solution is exited. When the solution is opened the next time on that client, the persistent data is displayed. If a tree is defined as persistent, then it cannot be stored on the server. See the Keep data on server command above.

This command rolls out a sub-menu with the following mutually exclusive options (only one can be selected):

•On First Use: Loads the tree on entering a page where it is used. Once loaded, it will not automatically be reloaded anymore. If you share the same tree on multiple pages, then the first time one of such pages is opened (doesn't matter whether it is a Top page or Sub page), the tree will be loaded and will remain in memory.

•On Every Page: Reloads the tree every time you open a page containing the tree, whether the page is a Top page or Sub page. You must be careful with this option: It can slow the processing if loading takes significant time. But this will ensure that the data is retrieved afresh for every page.

•Not Automatically: The tree will not automatically be loaded for you. You must use the Reload, Load from File, or Load from HTTP actions to load it. Alternatively, it can be created completely from scratch with the Append Node and Insert Node actions, without having to load data from any source. Note that you can use any of these five actions independently of the Load Data setting. That is, these actions can be used to reload your tree at specific moments even if Load Data is set to On First Use or On Every Page.

The default is On First Use.

The Save Data command rolls out a sub-menu with the following mutually exclusive options (only one can be selected):

•On Every Page Leave: Data in the tree is saved every time a page containing that tree is exited.

•On Any Solution Finish: Data in the tree is saved when the solution is exited, no matter at what point or how the solution is exited.

•On Last Submit: Data in the tree is saved when the workflow progresses as designed, from first page to last page, and when the last Submit button is tapped. If this option is selected and the solution is exited before the last Submit button is tapped, then data in the tree will not be saved.

•Not Automatically: The tree will not automatically be saved. You must use the Save, Save to File, or Save to HTTP/FTP actions to save data.

In the case of databases, there are options to save (i) modifications only; (ii) all rows; (iii) all rows if anything has been modified. If you wish to select an option that checks for modifications, then make sure that an OriginalRowSet has been created for the table; otherwise an error will be reported on validation.

The default is Not Automatically.

This command enables you to specify whether the data of the selected root node (page source) is automatically reset when a page is left. The following options are available:

•On Every Page Leave: The page source is reset on every page leave. Whenever a page is left, the page source will be reset—even if another page that is referencing the page source is still in use.

•On Last Referencing Page Leave: The page source is reset when the last page that references it is left. Essentially, a page source is reset only at the point when it is no longer in use by any page. Note that, if a sub page returns to a top page and both pages uses the same page source, then the page source will not be reset

•Not Automatically: The page source is not automatically reset when the page is left. If a data reset is required in a situation not involving a page-leave, then use the Reset action.

The default is Not Automatically.

Sets the selected node as the XPath context node of the page. An annotation to the effect is displayed below the node (see screenshot below). The XPath context of the page is the context node for all XPath expressions on the page.

This command can be toggled on and off. So, you can enable a node as the XPath context node of the page, or you can toggle off a node's setting as the XPath context node of the page. If a node is set as the XPath context node when another node already has this setting, then the setting is toggled off for the previously assigned node and toggled on for the newly assigned node.

Displays the Specify File dialog (screenshot below), in which you specify the file to use as the default file. Data from the default file will be used as the data of the page source. However, in order for the data to be used, the default file must have the same structure as the page source. Note that, when a default file is assigned to a page source, its structure is not automatically imported. To import the structure of the XML file, use the context menu command Import Structure from XML; see below. You can also manually create the structure of the page source to match the structure of the default file.

File is located on server

If the default file is located on the server, select the Server radio button (see screenshot below). The dialog now enables you to browse for a file (Absolute/Relative Path) or to specify the file via a global resource (File Alias or Folder Alias). Select the option 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 default 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.

This command is enabled when the root node of an XML page source is selected that has a default file assigned to it. Selecting it opens the default XML file in Altova's XMLSpy application, which enables you to work directly on the XML file while using the powerful editing and processing features of XMLSpy.

This command is enabled when the root node of an XML page source is selected that has a default file assigned to it. Selecting it embeds the XML data source in the design (.mtd) file. After a data source is embedded, the property Embedded is added to the annotation of the root node. See the sections Location of Project Files and Embed XML in Design File for more information about (i) the advantages and disadvantages of embedding, and (ii) alternatives to embedding.

This toggle command is enabled when a page source is associated with a deployable file, typically a default file. The deployable file will already be listed in the Files Pane.

•Toggling the command on selects the check box of the file in the Files Pane, thus deploying it.

•Toggling the command off de-selects the file in the Files Pane; the file will not be deployed.

Note that when a file is first added to the design, you are prompted about whether you wish to deploy the file or not.

You can add comments to the root node of a page source tree and all tree nodes (see screenshot below). The comment is added to the right of the node. To edit a comment (or delete it), double-click the comment and edit it.

The root node of every page source is a variable, for example $XML1 or $DB1. The List Variable Usage command lists, in the Messages Pane, all the usages of the selected root node variable. The items in the list are controls and actions in which the variable is used. (Variables are typically used in XPath expressions.) Clicking an item in the list highlights the control or opens the Actions dialog containing the variable usage.

Select XML, HTML, or JSON from the submenu that rolls out. Your selection specifies what type of data source you plan to target, and enables MobileTogether Designer to correctly process the incoming or outgoing data. You can change this selection at any time. A change will cause the data source to be re-parsed for the new data type.

Reloads the structure of the selected page source. The command is enabled only if the structure is based on an external resource, such as an XML file or DB. In the case of XML files, this means that if there is a default file, then the command is enabled.

If nodes have been manually added to the page source, then a dialog appears asking whether you want to remove or keep the added nodes. Click Remove to remove the selected nodes. You can deselect all nodes by clicking Deselect User Added, or you can deselect individual nodes. While the Remove button enables you to select which user-added nodes to remove and, conversely, which to keep, the Keep All. button keeps all user-added nodes, irrespective of whether they have been selected or deselected.

Opens a Browse dialog in which you can select the XML or HTML file from which to import the XML structure of the page source tree. If the tree already contains a structure, you will be prompted about whether one or multiple nodes of the existing structure should be retained or not. If you choose to retain the existing structure and the new structure cannot be merged into the existing structure, then the new structure is imported as a sibling of the existing structure. This command is not available for tree structures that have a root element named json.

Note:   When a structure is imported from an XML file, the file is set as the default file and the file's data is also imported.

Opens a Browse dialog in which you can select an XML file to which to export the XML structure of the page source tree. You can choose an existing XML file or create a new one. If you choose an existing file, the file's existing data will be overwritten by the exported structure. This command is not available for tree structures that have a root element named json and target a JSON data source.

Opens a Browse dialog in which you can select the JSON file from which to import the XML structure of the page source tree. If the tree already contains a structure, you will be prompted about whether one or multiple nodes of the existing structure should be retained or not. If you choose to retain the existing structure and the new structure cannot be merged into the existing structure, then the new structure is imported as a sibling of the existing structure. This command is available only for tree structures that have a root element named json and expect data from a JSON data source.

Note:   When a structure is imported from a JSON file, the file is set as the default file and the file's data is also imported.

Opens a Browse dialog in which you can select a JSON file to which to export the XML structure of the page source tree. You can choose an existing JSON file or create a new one. If you choose an existing file, the file's existing data will be overwritten by the exported structure. This command is available only for tree structures that have a root element named json and target a JSON data source.

This command is enabled for database type ($DB) root nodes. It opens MobileTogether Designer's Database Connection Wizard, with which you can connect to a DB data source. After connecting to the DB, you can select the table to add as the page source. If the new table data cannot be merged into the existing structure, then the new table structure is created as a sibling of the existing structure.

If the DB is shared (as a page source) by other pages in the design, then you are prompted to choose from the following options:

•Modify Shared Structure: The modifications you are about to make to the page source structure on this page will be shared on the other pages where this DB structure is used.

•Copy Structure: The structure is copied to a new page source, and its root element is given a different name. The original page source is removed. The new data structure is not shared any more with any structure on other pages. You can now modify this page source while leaving page sources on other pages unchanged.

•Cancel: Cancels the modification process.

This command is enabled for database type ($DB) root nodes. It opens MobileTogether Designer's Database Object Selector window, in which you can select the DB tables and views to import as a page source.

In order for data to be edited and saved, the tree of the page source must also include an OriginalRowSet element, which is a copy of the RowSet element. The original data is saved in the OriginalRowSet element, while edited data is saved in the RowSet element. When the page source is saved, the difference between the two trees, OriginalRowSet and RowSet, is calculated, and the page source is updated on the basis of the difference. If the modification is successful, then the modified data is copied to OriginalRowSet so that OriginalRowSet contains the newly saved DB data, and the modification process can be repeated.

Note the following points:

•The OriginalRowSet element is not created by default in the tree of the DB page source. To create it, right-click the root node of the DB page source and toggle on the command Create OriginalRowSet.

•The Create OriginalRowSet.command is enabled for database type ($DB) root nodes. It is a toggle command that creates/removes an OriginalRowSet data structure that contains the original data of the page source.

•Till the time modified data is saved to the DB, the original DB data is retained in the OriginalRowSet structure. This ensures that the original DB data is still available in the tree.

•To retrieve the original data of a DB row that has been modified but not yet saved, use the XPath function mt-db-original-row.

This command is enabled for database type ($DB) root nodes. It opens the Database Column Save Settings dialog, in which you can specify which columns should be saved to the DB data source.

The dialog displays the columns of the DB page source. You can specify which columns can be updated or can take inserted values. (Updates refer to modified data in existing row elements; inserted values refer to data in newly added row elements.) By default, the Insert and Update options of each column are selected together as a pair. If, however, you wish to specify different options for a column's Insert and Update options, check the Use separate filter settings for Insert and Update statements check box. Attributes with empty values can be converted to NULL values in the DB by checking that column's NULL check box. Note that missing attributes will always be saved as NULL.

Columns that cannot be updated (because they are user-defined, fixed-value, or calculated-value) will not have an Insert, Update, or NULL option check box. In the screenshot above, the ID column cannot be updated because it holds fixed values. Deselect the columns you do not want to update.

You can specify the order in which deletions, updates, and insertions occur by selecting the desired order in the combo box at the bottom of the dialog.

If you wish to reset the Save settings so that all columns are updated, click Reset to default.

If the DB page source has related tables, then selecting this command opens a dialog in which the related tables are listed. Here you can select how data in each of these related tables should be handled when the DB page source is saved. The following options are available: (i) Only modifications in the related table will be saved; (ii) all rows of the modified table will be replaced; (iii) the related table will not be saved.

This command is enabled for root nodes of the HTTP/FTP type ( that is, $HTTP root nodes). Depending upon whether the current page source request is made with HTTP/FTP, REST, or SOAP, the appropriate settings dialog will be opened: Edit Web Access Settings, RESTful API Request Settings, Choose WSDL File.

This command opens the Configure Caching settings dialog of the current tree. For a description of this dialog, see the section Data Sources (Data Sources) | Caches.

Enables the addition of elements and attributes relative to the selected node. Insert adds the node before the selected node. Append adds the node after the last node of that type. If you wish to add a node immediately after the selected node, go to the following node and use the Insert command.

This context menu item is available for tree nodes. A fixed value can be provided for the selected node when the page is loaded. Click the command and enter the value. This command is a toggle command. So, clicking it when a fixed value is already assigned will remove the value.

This context menu item is available for tree nodes. An XPath-generated value can be provided for the selected node when the page is loaded. On clicking the command, the Edit XPath/XQuery Expression Dialog is displayed. Enter the XPath expression to generate the value of the node. This command is a toggle command. So, clicking it when an XPath value is already assigned will remove the value.

Sets the selected node as a temporary node. Data in temporary nodes is not saved when the tree is saved. Since temporary nodes are outside the framework of valid workflow data, they are intended for use in calculations and for storage of any data that is not wanted as part of the final data.

You can add comments to the root node of a page source tree and all tree nodes (see screenshot below). The comment is added to the right of the node. To edit a comment (or delete it), double-click the comment and edit it.

This context menu item is available for DB nodes, and has a sub-menu with two commands:

•Is Primary Key: Sets the selected node as the primary key column if a primary key has not already been auto-detected during retrieval from the DB.

•Is Auto Increment: Sets the selected node to auto increment. The node then becomes read-only.

Primary keys in MobileTogether Designer

Primary keys in DBs typically are auto-incrementing. When this is the case and a new row is added to a table, the primary key column of the added row is automatically incremented. In MobileTogether Designer, when a table is retrieved the primary key and auto-increment information is automatically retrieved and displayed in the Page Sources Pane (see screenshot below).

If auto-retrieval of this information was not successful, the context menu of tree nodes contains toggle commands that enable you to correctly annotate nodes (see screenshot below).

If the primary key column is not auto-incrementing, new primary key values for appended rows must be automatically generated using an XQuery expression. This is because primary key columns cannot be edited. The XQuery expression is inserted by using the primary-key node's context menu command, Ensure Exists before Page Load (XPath Value). In the example below, a new value is generated for the primary key @id by using the following XQuery expression:

let $all := $DB1/DB/RowSet/Row/@id

let $ids := remove($all, index-of($all, ""))

let $id := if (empty($ids)) then 1 else max($ids) + 1

return $id

Sets the selected node as the XPath context node of the page. An annotation to the effect is displayed below the node (see screenshot below). The XPath context of the page is the context node for all XPath expressions on the page.

This command can be toggled on and off. So, you can enable a node as the XPath context node of the page, or you can toggle off a node's setting as the XPath context node of the page. If a node is set as the XPath context node when another node already has this setting, then the setting is toggled off for the previously assigned node and toggled on for the newly assigned node.

Copies the XPath locator expression of the node to the clipboard. The locator expression starts at the root node. For example: $XML1Products/Product is the locator expression of the Product node.

Selects the controls in the design diagram that are associated with the selected node. Such associations are typically page source links between the node and page controls.