AX1367

ShowFormDialog function

Opens a designated form-enabled file as a form dialog. Users can double-click on the cell that contains the function to open the form.

This function is intended to be used within spreadsheet Axiom files, to launch an Axiom form that is designed to be used as a dialog. The behavior is the same as when using the Show Form Dialog command for custom task panes and ribbon tabs.

This function can be used in one of two ways:

  • As a "hyperlink" to launch a dialog to perform a particular task. The user can open the dialog from the file, perform the task, and then return to the file. The actions performed in the dialog have no impact on the source file. This use case is just an alternate way for users to get to the dialog.

  • As a user interface to perform an action on the current file. The user can open the dialog from the file, make selections in the dialog, and then apply those selections to the current file using form state or by using commands that can be executed on the client. In this use case, the form is specifically designed to work together with the file where it is being launched.

Syntax

ShowFormDialog("DisplayText", "DocumentPath", "FormState")

Parameter Description
DisplayText

The text to display in the cell.

The DisplayText displays as normal text in the cell. If you want the text to appear like a hyperlink on a web page, you must manually apply the font formatting to the cell.
DocumentPath

The form-enabled file to open when the user double-clicks on the cell. Specify the file name and path in the Axiom Software virtual file system. The path is the folder path as it would display in Axiom Explorer—for example: \Axiom\Reports Library\Forms\SelectionForm.xlsx.

FormState

Optional. One or more form state key/value pairs to pass to the target file when it is opened. Form state key/value pairs are specified as follows:

FormStateKey1=Value;FormStateKey2=Value

Separate multiple form state key/value pairs using semicolons. If a value contains a semicolon, then it must be preceded by a backslash (\) so that Axiom does not treat the semicolon as a delimiter. Equals signs within a value (such as to pass a filter criteria statement as a value) do not need to be specially treated.

Form state values can be read in the target file by using the function GetFormState("FormStateKey"), or by configuring a component to use the [FormState=FormStateKey] tag.

All non-numeric entries must be placed in double quotation marks, unless you are using cell references to reference the text held in another cell. However, the Boolean values TRUE and FALSE do not need to be in quotation marks.

Passing form state values

When you use the FormState parameter to pass form state values from the current spreadsheet into the target form, the behavior is as follows:

  • When the ShowFormDialog function is double-clicked, the designated form state values are set in the current spreadsheet, which causes them to be passed into the target form when it is opened. In the target form, GetFormState functions and components using the [FormState] tag for the designated keys will return the values defined in the function.

  • The form state values in the ShowFormDialog function overwrite any existing values for the designated form state keys in the spreadsheet. For example, if the spreadsheet has an existing value Blue for the form state key Color, and the function contains Color=Red, then when the function is used the value of Color is set to Red. This is the only way that the spreadsheet can change an existing form state value. Form state values set by ShowFormDialog are actual form state values, not default values.

  • If the spreadsheet contains GetFormState functions for the designated form state keys, these functions will not update to show the new value until the spreadsheet is refreshed. It is not necessary for the spreadsheet to contain any GetFormState functions—the values in the ShowFormDialog function can be used solely to impact the target form.

  • If the spreadsheet contains other form state values that are not listed in the ShowFormDialog function, those existing values are passed into the target form as normal.

Remarks

  • To obtain a file path for use in the function, you can right-click a file in Axiom Explorer or the Explorer task pane and choose Copy document path to clipboard, then paste the path into the function parameters (or into a cell that you will reference).

  • The Axiom Double-Click setting does not need to be enabled for the sheet in order to use ShowFormDialog.

  • If your system is deployed in an environment where users work in different system languages, then you should use system folder names in any file paths. For more information, see Using system folder names.

  • ShowFormDialog is a non-volatile function.

Examples

=ShowFormDialog("Select Items","\Axiom\Reports Library\Forms\SelectionForm.xlsx")

This example opens the specified form-enabled file as a dialog.

=ShowFormDialog("View Details","\Axiom\File Groups\Budget 2020\Utilities\Details.xlsx";"Acct=6000")

This example opens the specified form-enabled file as a dialog, and sets the value of the Acct form state key to 6000.

See also