Go to Subpage
Goes to the specified sub-page when triggered. The subpage to go to is selected from the Go to Subpage combo box (see screenshot below), which lists all the subpages in the project. In the screenshot below, an OnLabelClicked event has been set to go to the Orders subpage of the MobileTogether project. Alternatively, the name of the subpage can be obtained via an XPath expression, for example: "Orders" or $XML3/DataSources/Subpage[@id="Name"]/@name.
The Go to Subpage action has the following settings:
•Parameters: If parameters have been declared on the selected sub page, then each parameter of that sub page is now listed below the sub page entry, and a value can be passed to each parameter. In the screenshot above, for example, a value is defined for the parameter named $a. It is an error if no value is passed to a mandatory parameter. If the sub page is not selected via the combo box but by using an XPath expression, then the name of the sub page is not generated till runtime. Since no parameters can, therefore, be known at design time, instead of any parameter names being displayed, an entry for Parameters is displayed. Here, you can enter an XPath map expression or array expression to define parameter values, for example: map{"a": "a-value", "second-param": "second-param-value"} or [("a-value"), ("second-param-value")]. If you enter an array expression, (i) the order of sequences in the array must match the order of parameter declarations of the sub page, and (ii) values for optional parameters may not be left out of the array (an empty sequence can be entered for a parameter value that you wish to leave empty). Note that you can use other parameters when defining the value of a parameter.
•Source XML: Specifies whether and how subpage data should correspond to page sources in the originating page. This definition is entered in the Subpage Data Mapping dialog, which is accessed by clicking the Additional Dialog button of the Source XML field. See the section "Source XML of subpages" below for a detailed description of this dialog.
•Load Subpage Message: In the event that the subpage is transmitted via a server request: If the check box is selected, this message is shown in a progress dialog while the subpage loads. See screenshot above.
•Close Subpage Message: In the event that the subpage is transmitted via a server request: If the check box is selected, this message is shown in a progress dialog while the subpage closes. See screenshot above.
•Show Subpage as modal dialog: If this option is unchecked, then the top page in the display is overlaid by the subpage; (the user can return to the top page by tapping the Back button). If this option is checked, then the subpage is opened in a separate window above the top page (known as a modal dialog)—with access to top-page content being disabled. If the user taps outside the modal window, then the actions specified for the OnBackButtonClicked page-event are executed. If no action is specified for this event, then the subpage is closed and execution returns to the top page.
Defining modal dialogs
The following definitions can be applied to modal dialogs:
•You can set the dimensions of the modal dialog window via the XPath expressions of the Width and Height settings.
•If the optional Height setting is not specified, then the height will be only as much as is required to fit the content, up to a maximum of the device's viewport height. If a greater height is required, then a scrollbar is automatically added to the modal dialog.
•Dimension values that you enter may be a number (for pixel dimensions) or a string that contains a number value and a % sign (to specify the dialog's dimension as a percentage of the viewport's dimension).
•In the screenshot above, the dimensions have been set to the device-specific width and height values (viewport dimensions) that are obtained dynamically from the device at run time.
•You can choose whether the modal dialog should: (i) have the same single set of dimensions for both portrait and landscape orientations, or (ii) use a different set of dimensions for each orientation (that is, one set of dimensions for portrait and another for landscape).
•If the modal dialog is defined to have a single set of dimensions for both orientations, then the width and height dimensions are taken from the portrait orientation of the page that was current before the Go to Subpage action was executed. If this option was selected, then the modal dialog will have the same set of width and height values in both orientations. The effect is that the modal dialog does not change size when the orientation is changed.
•From a subpage that is displayed as a modal dialog, you can go to another subpage, which you can also choose to open as a modal dialog above the previous modal dialog.
•Relative dimensions (percentage values) of all modal dialogs—even when they originate from other modal dialogs—are calculated relative to the dimensions of the device's viewport.
•If a subpage is opened from a modal dialog without the modal dialog option being selected, then the new subpage will have the same dimensions as the modal dialog and will overlay it. It will look as if the new subpage has replaced the previous subpage.
Source XML of subpages
Every subpage must have at least one page source in order for the subpage to be used effectively. Data in page sources of subpages can be mapped to data in top page sources, or the data in subpage sources can be left unmapped. If mapped, then subpage data is transferred to the mapped nodes of the top page when the subpage is closed. The behavior of the source XML of subpages is defined in the Subpage Data Mapping dialog (screenshot below left). To access this dialog, click the Additional Dialog button of the Source XML field of the Go to Subpage action definition (see description above).
The following subpage data handling possibilities are available:
•Subpage data is not mapped. In this case, page sources of subpages are handled independently of the subpage-data-mapping mechanism.
•A subpage source is mapped to a top page structure that is exactly the same; even the names of elements and attributes are the same.
•A subpage source is mapped to a top page source that has a different structure and/or different attribute/element names.
In the Subpage Data Mapping dialog (screenshot above left), the page source tree of the subpage is displayed in the right-hand source tree pane, while the page source tree of the top page is displayed in the left-hand source tree pane .
•Select the subpage page source from the combo box above the (right-hand) subpage pane. This combo box lists all the page sources of the subpage. Note that the subpage name is listed above the subpage pane.
•To select the top-page page source to be mapped, first click the Additional Dialog button above the (left-hand) top page pane. This displays the Choose XML dialog (screenshot above right), which contains all the page sources of the top page. Select the node that you want to map to the subpage data. In the screenshot above, the PrivateAddresses node has been selected in the Choose XML dialog. As a result, the descendants of PrivateAddresses are displayed in the top page source tree pane and PrivateAddresses, the mapped node, is listed above the pane.
In the case described by the screenshot above, the mapping is automatically done between the two page sources since both XML data structures are identical, right down to the names of elements. In the screenshot below a mapping between elements is constructed by dragging a node from the left-hand pane onto a node in the right-hand pane. This is because the two data structures are not identical (the first element, S, must correspond to the third element, Street).
In the case described by the screenshot below, the content of the subpage data node Income/Months/Month is mapped to the top page data node Income (indicated by the title of the pane).
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.