AX1298

Using an Axiom form as a custom dialog

You can use an Axiom form as a dialog in the Axiom Software Desktop Client (Excel Client or Windows Client). The dialog can be used for any task that can be performed using Axiom form features.

For example, imagine that you want certain users to be able to add new items to a reference table. Instead of granting them access to Open Table in Spreadsheet or to a save-to-database report, you can create an Axiom form that allows users to input the necessary information and then save it to the reference table. The user could launch the Axiom form dialog from a ribbon tab or a task pane, or from within an Axiom spreadsheet file. Using a dialog instead of a spreadsheet file provides the user with a more controlled and guided environment for performing the task.

Axiom form dialogs can interact with the active client spreadsheet using "form state" values and various commands, or they can operate as "stand-alone" dialogs that have no relationship to any open files. In the case of a stand-alone dialog, the interactive elements of the form are set up just like a standard form, with no use of form state. Form state should only be used if the form dialog will be launched in a way where the active client spreadsheet file is always known. For example, you can use the ShowFormDialog function to launch the dialog from within a particular file, thereby guaranteeing that any client-side actions performed by the form will be performed on that known file.

NOTE: This section discusses how to create an entire form to be used as a custom dialog within the Desktop Client. If instead you are looking for information on how to create a dialog to be displayed within an Axiom form, see Dialog Panel component for Axiom forms.

Designing an Axiom form to be used as a dialog

The Axiom form to be used as the dialog should be configured as follows:

  • Set the Canvas Size of the form (width x height) to a dialog-appropriate size. When a form is used as a dialog, the canvas size sets the window size of the dialog.

    A good starting point is 700 x 400. To help you design the form to fit the target canvas size, make sure to enable Options > Show form canvas area in the Form Designer. If the contents of the form exceed the specified canvas size, scroll bars will be present in the dialog.

  • It is recommended to define a form Title. This title will be used as the dialog title. Otherwise, the file name of the Axiom form will be used.

  • If you want the dialog to interact with the active client spreadsheet, then you can configure the file to use form state and/or various commands that execute on the active spreadsheet file.
  • To allow users to close the dialog, you can use the Close Dialog command on a Button component. Users can also close the dialog by clicking the X button on the dialog window. For more information, see Configuring close options for a form dialog.

The form size and title can be set in the Form Properties dialog. To open this dialog, click Edit Form Properties at the top of the Form Assistant or the Form Designer.

While you are designing the form, you can use Forms > Preview Form as Dialog to see the form as it will display when it is launched as a refresh form. This may assist you in determining the appropriate form size.

Launching the dialog

There are two ways that you can launch a form as a dialog within the Excel Client or the Windows Client:

  • Show Form Dialog command: This command can be used to open the dialog from a custom ribbon tab or task pane. For more information, see Show Form Dialog command.

    In general, this approach should only be used with "stand-alone" dialogs that do not interact with the active client spreadsheet. An exception would be if the command is used in a task pane that is associated with a specific file—in this case you could use the task pane to launch a form dialog that is designed to be used on that associated file.

  • ShowFormDialog function: This function can be used to open the dialog from within a particular file. For more information, see ShowFormDialog function.

    This approach can be used to launch any type of form dialog—stand-alone dialogs or dialogs that interact with the current file.

The user must have at least read-only access to the designated form in order to open it using either of the above options. If the user does not have permission to the file, an error message will display when the user attempts to open the form. When configuring user security permissions for the form, you can optionally clear the Show in Explorer option if the user only needs to access the file via indirect methods such as Show Form Dialog. The form will not display when the user browses file libraries.

When using either of these features, you have the option to set certain form state values and pass them into the target form. This is most useful when using the function. For example, you may want to use the ShowFormDialog function in a calc method, to launch a dialog that shows more details about the current row. In order to filter the dialog to show only the data for the current row, you must pass in form state values that identify the current row (such as the account number for the row). By using a parameter in the ShowFormDialog function, you can specify the account for the current row and pass that into the form dialog when it is launched.

Dialog behavior

When the dialog opens, it is "modal". This means that while the dialog is open, users cannot interact with the currently active spreadsheet file or with any ribbon tab or task pane in Axiom Software. The user must close the dialog before they can return to using the main application.

The user can close the window using the X button in the top right corner. You can also design the Axiom form with a button that uses the Close command. For more information, see Configuring close options for a form dialog.

If the dialog contains hyperlinks to documents that will not be opened in the current window, then the dialog automatically closes before opening the document.