AX1406

Using form state values in the active client spreadsheet

The active client spreadsheet is the spreadsheet that is active in the Desktop Client General term for using either the Excel Client or the Windows Client, both of which are installed to the user's desktop. when the Axiom form is opened as a dialog or a task pane. You can set up this spreadsheet to return the form state values that are passed from the Axiom form and use these values in some way, such as to filter the data in an Axiom query. You can also set default form state values in the spreadsheet that will be passed to the Axiom form when it is opened.

Returning form state values

When the Apply Form State button is used in the Axiom form, the current form state values in the Axiom form are passed to the active client spreadsheet. In order to use those values within the spreadsheet, you must use the GetFormState function to return them.

The GetFormState function takes the following parameters:

For example, imagine that the Axiom form contains a Combo Box component that is set up with the following FormState tag: [FormState=VPName]. When a user selects a value from the combo box—for example, Jones—that value is stored in form state as the VPName value. In order to read this value within the active client spreadsheet, you would use the following formula:

When using the GetFormState function in the client spreadsheet, keep in mind the following:

• The GetFormState function returns form state values for the current file, it does not read the values from other files. When GetFormState is used in the client spreadsheet, the function does not know what the form state values are in the Axiom form until those values are passed from the form to the spreadsheet (thereby becoming the form state values for the spreadsheet).

• Form state values can only be set within an Axiom form (or by launching an Axiom form using ShowFormDialog). Until the form state values are set, the GetFormState functions in the client spreadsheet will return blank unless the DefaultValue parameter of the function is used to set a default value for each form state key.

The GetFormState function simply returns the current form state value; it does not have any other impact on the spreadsheet file. It is up to the file designer to use that value in a way that impacts the spreadsheet—for example, to use the value in an Axiom query filter, or to include the value in a save-to-database process.

Setting form state values

In the active client spreadsheet, you can set a default value for a form state key within the GetFormState function. For example:

Defining a default value in the function does not actually set the value for the form state key. You can change the default value in the function, and as long as no "real" value has yet been set for the form state key, the function will update to return the new default value. However, once a form state value has been set by a form (using Apply Form State), then the function will return that value and the default value is ignored.

In this example, the GetFormState function in the spreadsheet returns the default value of Smith. When the Axiom form is opened, this default value is passed into the form and becomes the current form state value for VPName in the form (overriding any default value set in the form). If an interactive component such as a combo box is configured to set the value for VPName, then you can use the component to change the value to something like Jones. This sets a "real" value for the VPName form state key. When the Axiom form passes its form state values to the client spreadsheet using Apply Form State, the GetFormState function in the spreadsheet will now return the value Jones. Now that a real value has been set for the form state key in the form, the default value in the function is ignored.

Generally speaking, form state values are set in the form, not in the active client spreadsheet. The active client spreadsheet can only set default values. However, there is one exception to this rule. When using the ShowFormDialog function to open an Axiom form dialog, you can define form state values in the function and set those values in both the spreadsheet and the form when the function is used. For example: