AX1290

Using an Axiom form as a refresh form

You can use an Axiom form as a refresh form, as an alternative to defining refresh variables. This works as follows:

• You design a separate Axiom form to display as the refresh form dialog. This form collects the user's inputs and stores them using the "form state" feature.

• In the file where you want the refresh form to display, you use a special tag to tell Axiom Financial Institutions Suite to open the Axiom form as a dialog when the file is refreshed. You set up the file to read the desired values from form state, and then use those values to impact the data refresh.

Generally speaking, using an Axiom form as a refresh form requires more setup than refresh variables, but it is also more flexible. For more information on the differences between the two features, see Setting up refresh dialogs for Axiom files.

NOTE: This section discusses how to create an entire form to be used as a refresh form 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 refresh form

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

• The form must be set up to store one or more values in form state memory. These values are the values that you want to send to the active client spreadsheet to affect the refresh of that file. For more information, see Passing values between an Axiom form and the active client spreadsheet (form state).

• The form must use a button that is configured with the following commands: Apply Form State and Close Dialog.

  • The Apply Form State command sends the updated form state values from the Axiom form to the active spreadsheet file. Note that the Refresh mode shortcut parameter for the command is ignored when the form is used as a refresh form. Instead, the level of refresh performed is the level selected by the user when they triggered the refresh from the active spreadsheet file. For example, if the user selected to refresh the active sheet only, then that is the level of refresh that will occur.
  • The Processing Step shortcut parameter for the Close Dialog command must be set to Active Client Spreadsheet - After Processing.
  • The order of the commands does not matter; the Close Dialog command allows for executing other commands at the After Processing step.
  • Both commands must be on the same button in order to enable the "auto refresh" behavior of the refresh form.

• The form can optionally use a second button that is also configured with the Close Dialog command, this time with the Processing Step set to Active Client Spreadsheet - Before Processing. The user can click this button to cancel out of the dialog and cancel the refresh. If no cancel button is provided on the form, then the user can click the X button on the dialog window to close the dialog without refreshing.

• 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.

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.

When deciding where to save the file and what to name it, keep in mind that another file will require the continued presence of this file. If the Axiom form is deleted, moved, or renamed, then the file that is configured to use the Axiom form as a refresh form will no longer work. You may want to name the file so that the relationship between the two files is clear, or save it to a designated folder that holds required "supporting" files such as this one.

Enabling the refresh form for the Axiom file

To launch an Axiom form as a refresh form when an Axiom file is refreshed, place the following tag in a cell within the first 500 rows of a sheet:

For best results, the tag should be placed on the same sheet where the data query is located. This ensures that the refresh form will display if the user chooses to refresh the current sheet only. If it is placed on a different sheet, then the refresh form will only display when the entire workbook is refreshed.

You can manually type the tag, or you can right-click the cell and then select Axiom Wizards > Insert Refresh Dialog. This wizard prompts you to select the Axiom form to use as the refresh form, and then places the tag in the cell with the full path to the selected file (using document shortcut syntax). If you manually type the tag, you can enter the path as a normal Axiom file path or using document shortcut syntax.

The next time you open the document after saving, the file parameter will be automatically converted into a system-managed document shortcut (you can tell the difference by the presence of a _tid parameter on the end of the shortcut). This is to make the file reference "repairable" in cases where the file is renamed or moved. If you need to change the entry to point to a different file, simply enter the path or document shortcut as you would have originally (or use the wizard again), and the path will be converted again when you save the file. Note that if the tag is a result of a formula instead of directly within the cell, then the conversion will not occur and the file reference will not be repairable.

The presence of the RefreshDialog tag signals to Axiom Financial Institutions Suite that you want to open an Axiom form as a refresh form. The file path tells Axiom which Axiom form to open. For example:

NOTE: Users must have at least read-only access to the designated RefreshDialog file in order to open it as a refresh form. Simply having access to the file that calls the refresh form will not automatically grant access to the RefreshDialog file.

Using GetFormState to return values selected in the refresh form

As the user interacts with the refresh form dialog, their inputs and selections are stored in form state memory. When the user clicks the Apply Form State button in the dialog, those form state values are passed from the Axiom form to the spreadsheet file. The spreadsheet file must be set up to read these values using the GetFormState function. These values can then be used to impact the data refresh in some way, such as to define the filter an Axiom query.

For more information, see Passing values between an Axiom form and the active client spreadsheet (form state).

Configuring when the refresh form displays

On the Control Sheet, review the Refresh Forms Run Behavior setting (under Data/Zero Options) and configure it as desired. By default, it is set to OnManualRefreshOnly, which means the refresh form will only display when a user manually initiates a refresh in the file. Refreshes that occur automatically when a file is opened will not display the refresh form. The available options are as follows:

• Off: The refresh dialog is disabled and does not display when the file is refreshed.

• OnManualRefreshOnly (default): The refresh dialog only displays when the file is manually refreshed (by clicking Refresh).

• OnOpenOnly: The refresh dialog only displays when the file is refreshed on open. This occurs if an Axiom query is set to Refresh data on file open, or if the workbook is set to Refresh all Axiom functions on open.

• OnManualRefreshAndOpen: The refresh dialog displays when the file is refreshed on open, and when the file is manually refreshed.

The refresh dialog is always disabled when the file is refreshed by an automated process, such as Process Plan Files, File Processing, or by any Scheduler task that opens and refreshes the file.