AX1291

Passing values between an Axiom form and the active client spreadsheet (form state)

When an Axiom form is used as a dialog or a task pane within the Axiom Software Excel Client or Windows Client, it can accept values from the active client spreadsheet and then pass changed values back to that spreadsheet. Active client spreadsheet means the spreadsheet that is currently open and active in the client when the form dialog or task pane is opened. This interaction between form and spreadsheet is accomplished by using the "form state" feature for Axiom forms.

When using form state, certain designated values are stored in memory. This "form state memory" can then be shared between the active client spreadsheet and the form (dialog or task pane). When the form is opened, the existing form state values in the active client spreadsheet are passed into the form. Users can then use the form to change the form state values, and then pass the new values back to the active client spreadsheet.

For example, you may have a form state key named Dept, to store a department code. You can set a default value for Dept in the spreadsheet file, and pass it into the form when it is opened. You can use interactive components in the form to change the value of Dept, and pass that changed value back to the spreadsheet file. Both files can reference the Dept value as needed, such as to impact data queries.

Setting form state values

Form state values can be set as follows:

  • In the Axiom form, interactive components can be configured to use the FormState tag, in order to store the interactive value in memory. For example, instead of storing the selected value of a combo box to the Selected Value field in the Form Control Sheet, the selected value can be saved to memory using a designated form state key, such as [FormState=Dept].

  • In the Axiom form, a FormState data source can be used to set any form state value. This option can be used when the value you want to save is the result of a calculation in the spreadsheet, instead of the direct selection of a interactive component.

  • In either file, the GetFormState function can be used to set a default value if the form state key does not yet have a set value. This is the primary means of setting "starting values" in the spreadsheet file, to pass into the form. It can also be used in the form to set starting values.

  • In the spreadsheet file, the ShowFormDialog function can be used to set form state values as part of launching the form dialog, thereby causing the values to be passed into the form.

Returning form state values

Form state values can be returned as follows:

  • In either file, the GetFormState function can be used to return the value for a designated form state key. For example, GetFormState("Dept") returns the current value of Dept.

  • In the Axiom form, if an interactive component is configured with a FormState tag, that component will return the current value of the designated form state key. For example, a combo box that is configured with [FormState=Dept] will return the current value of Dept in the combo box. However in this case, the interactive component can also be used to change the value, by selecting a new value from the combo box.

Passing form state values

Form state values can be passed between the files as follows:

  • When the form is opened, the current form state values for the active client spreadsheet are automatically passed into the form. If the form is being opened as an associated task pane, then there is only one opportunity to pass values from spreadsheet to form, when the task pane is initially opened. But if the form is opened as a refresh form or by using the ShowFormDialog function, then every time the form is opened, the current spreadsheet values are passed into the form.

  • In the Axiom form, values can be passed from the form to the active client spreadsheet by using a button configured with the Apply Form State command. This command takes the current values in the form and passes them to the spreadsheet, including the ability to trigger a refresh within the spreadsheet.

Form State Example

Imagine that you want to use an Axiom form as a "refresh form" for a report. You want the user to be able to select values within the Axiom form to determine what data will be brought into the report. In order to share the selected values in the Axiom form with the active client spreadsheet, you must save these selected values to form state memory.

For example, the Axiom form contains a combo box where a user can select a VP name. You want to pass this selected VP value to the report file so that it can be used to define a filter for an Axiom query. This process works as follows:

  • The Selected Value cell for the combo box is configured with a FormState tag, such as [FormState=VPName]. This tag tells Axiom Software to store the value in form state memory instead of writing it back to the cell, and define the identifying key name for this particular form state value ("VPName").

  • The user selects VP name "Jones" from the combo box. This value is stored in form state for the Axiom form, as the current value for VPName.

  • The user clicks a command button that is configured with the Apply Form State command. This command sends the current form state values from the Axiom form to the active client spreadsheet (the open report in this case).

  • The report file is configured with GetFormState functions to read the form state values. When the form state values are updated from the Axiom form, the function GetFormState("VPName") returns the value Jones. This value can now be used in the Axiom query filter.

See also