AX1598

Sharing variables between parent and child forms

When using embedded forms, you can share a set of variable values between the parent and child forms in the shared form instance. These variables are known as shared variables. The shared variables feature allows all forms within the shared form instance to remain in sync for certain important values.

When a user views a form with embedded forms, Axiom Software maintains a single set of shared variables for all forms within the shared form instance. When any form in the instance needs to look up the current value for a specified variable, it looks up the value from this shared list. This shared list is stored in memory by the Axiom Application Server.

Shared variable values can flow in either direction. The variable value can be set in the parent form and then referenced by the child forms, or it can be set in a child form and then referenced by the parent (and other child forms).

Example shared variable flow

Variables and their values can be defined using the following methods:

• SetSharedVariable function: Each time this function is evaluated, it sets the current value of a named shared variable to the value defined in the function, overwriting any existing value for the variable. This method takes precedence over any other method of setting the variable value.

• Interactive component: An interactive form component, such as a combo box, can be configured to store its value using a named shared variable. Each time the component value is submitted to the source file, it sets the current value of the shared variable to the component value, overwriting any existing value for the variable.

• Apply Shared Variable command: A button in an Axiom form can be configured to use this command, which sets the value for one or more named shared variables. When a user clicks the button, the variables are set to the specified values, overwriting any existing value for the variables.

• GetSharedVariable function: If no value currently exists for a named shared variable when this function is evaluated, then the value of the variable is set to the value defined in the DefaultValue parameter of the function. This approach only works once, when the variable has no defined value. Once the variable has a value, the DefaultValue parameter is no longer evaluated and cannot affect the value of the variable.

Regardless of how the variable value is defined, the GetSharedVariable function can be used to reference the value in any form within the shared form instance.

It is recommended to use a dedicated sheet in each file to define and/or reference the shared variables. For example, the parent and child files could all contain a sheet named SharedVariables. In the parent file this sheet might contain SetSharedVariable functions to set the values, and then in the child files the sheet would contain GetSharedVariable functions to reference the values. Or the sheets might contain a mix of functions if some variable values are set in the parent file and other variable values are set in the child files.

This dedicated sheet is not required, but it simplifies form design to have all shared variables listed in a single known place within all of the related files. If instead the functions are scattered around different sheets, then it may become difficult to locate, review, and troubleshoot the variables.

NOTE: If any form in a shared form instance changes the value of a shared variable, the value is immediately available to the other forms. However, a form update must be triggered in the other forms in order to read the new value and refresh the form display. If a form is not updated after the value has changed, it will continue to reflect the previous value for the variable. Keep in mind that triggering an update in any child or parent form does not automatically cause the other forms to be updated. For more information on the update behavior for the forms in a shared form instance, see Form session and update behavior for embedded forms.

Defining shared variables using SetSharedVariable

The SetSharedVariable function sets the value of a named shared variable whenever the function is calculated. You should use the SetSharedVariable function when the value for the variable is derived from a data query, or by using calculations within the form source file. The SetSharedVariable function uses the following syntax:

For example, imagine that the parent form is a template that will be used to create form-enabled plan files. The plan file contents are sourced from a series of child forms (utility files) displayed within an Embedded Form component. When a child utility file is opened in the Embedded Form component, it needs to know the current plan code for the parent plan file, so that the child form can retrieve the appropriate data for the plan code and save back data to the appropriate plan code.

Within the parent template, the current plan code is typically retrieved by using a GetFileGroupProperty data lookup. This data lookup is typically placed on a dedicated sheet (such as "Variables") that retrieves various values used by the template. In the following example, the data lookup result is returned into column D, but we are reading the final values from column A (so that we can use formulas to apply different values for the template versus the resulting plan files).

To share this plan code value with the child utility forms, the parent template must use a SetSharedVariable function that references the result of the GetFileGroupProperty data lookup, such as:

When the SetSharedVariable function is calculated, the value of the shared variable (as stored in memory for the shared form instance) is set to the result of the function, overwriting any existing value for the variable. In this example the value of the variable is now 22000. The child utility forms can use the GetSharedVariable function to return the current variable value and apply it to data queries, save-to-database processes, and wherever else the value is needed.

For this particular variable example of PlanCode, the value is static. The data lookup that provides the value is only configured to run on open, so the variable value will not change during the current session. But you may have other types of variables where the value could change during the current session, and in that case the variable value will be updated whenever the SetSharedVariable function resolves to a new value.

Keep in mind the following when using the SetSharedVariable function:

• Only one SetSharedVariable function can be used per variable name, in all forms within the shared form instance. Since the value of the variable is set each time the function is calculated, having multiple instances of the function for a single variable name will result in a situation where the last function to be calculated "wins".

• The SetSharedVariable function can be used in either the parent form or any of the child forms, depending on where the variable value is originated. Again, make sure that there is only one SetSharedVariable function per variable name. All other forms in the shared instance should use a GetSharedVariable function to retrieve the value. The GetSharedVariable function can set an initial value for the variable if needed, which will then be overwritten by a SetSharedVariable function if present.

Defining shared variables using interactive components

Interactive components in Axiom forms can be configured to save their selected value to a named shared variable, instead of writing the value directly to the form source file. You should use this approach when the value of the shared variable is set based on the user's selection for an interactive component, such as a combo box, text box, or check box.

To configure a component to store its interactive value as a shared variable, use the SharedVariable tag. Use of the SharedVariable tag differs slightly depending on what type of interactive component you are configuring:

• For stand-alone components that typically place the interactive value in a component property—such as the Selected Value property for a ComboBox component—the SharedVariable tag is placed in the relevant component property on the Form Control Sheet.

• For content tags that typically place the interactive value in a target cell in the spreadsheet—such as when using the Select tag in a Formatted Grid component—the SharedVariable tag is included as a parameter in the content tag (instead of using the TargetCell parameter).

The syntax for the SharedVariable tag is as follows:

The presence of the SharedVariable tag tells Axiom Software that you want to store the value as a shared variable instead of within the target cell. The VariableName defines the name under which the value will be stored in the shared variables.

For example, if you want the value of a Combo Box component to be stored as a shared variable, you would place the following tag in the Selected Value cell for the component:

When using the SharedVariable tag, the contents of the Selected Value cell itself are never changed. The selected value is only stored in memory as a shared variable; it does not get written to the file. The only way to reference this value is to use the GetSharedVariable function.

When using this approach, you should also add the variable name to your designated SharedVariables sheet (if using the recommended setup described earlier in this topic), and then use GetSharedVariable function to return the current value of the variable. Any other components or formulas that need to use the selected value of the component should reference this cell on the SharedVariables sheet. You can also use this GetSharedVariable function to set an initial value for the variable, if the component needs to start with a particular value. When the form is first loaded, this initial value will be set as the variable value and therefore displayed as the selected value in the component that uses the variable.

IMPORTANT: Do not use a SetSharedVariable function to set an initial value for the component. If you do this, the SetSharedVariable function will calculate each time the form is updated, and overwrite the current value of the variable back to its original value. Instead, you must use the DefaultValue property of the GetSharedVariable function if you want to set an initial value for the component.

As noted, SharedVariable tags can also be used with content tags in Formatted Grid components. For example, if you want the value for a Select tag to be stored as a shared variable, you would set up the Select tag as follows:

Shared variables can be used with the following components:

Component	Feature or Setting	Notes
Check Box	Is Checked	To set an initial value using the GetSharedVariable function, use True (checked) or False (unchecked). This is also how the function returns the variable value after a user has interacted with the check box.
Combo Box	Selected Value	N/A
Date Picker	Selected Date	To set a default value using the GetSharedVariable function, use a date string such as "12/31/2018".
Formatted Grid	CheckBox tag DatePicker tag Select tag Selected Row ID TextArea tag	To set an initial value for the CheckBox tag using the GetSharedVariable function, use 1 (checked) or 0 (unchecked). This is also how the function returns the variable value after a user has interacted with the check box. If the text input for a TextArea tag contains line breaks, then the cell containing the GetSharedVariable function must have Wrap Text enabled in order to display those line breaks when returning the value. For thematic grids, this can be accomplished by applying a column style such as wrap-text. If the TextArea tag is numeric, the number format will be taken from the cell containing the tag. Normally the number format is taken from the target cell, but when using a shared variable there is no target cell. The note for the Text Box component also applies when using the TextArea tag.
Hierarchy Chart	Selected Value	N/A
Map View	Selected Value	N/A
Pie Chart	Selected Label	N/A
Text Box	Text	When returning the variable value using the GetSharedVariable function, it is returned as a string value, regardless of the cell formatting. If you want to use cell formatting to display a numeric value, wrap the function in a Value function, such as: =Value(GetSharedVariable("RunningTotal")) This formula will error if the shared variable does not have a value, so you can either use an IF function to handle the no value case, or you can define a default value in the GetSharedVariable function. If the text box type is Input Mask, and Preserve Input Mask is enabled, then any default value in the GetSharedVariable function must use the input mask format if you want it to display that way. Once the actual value is set, it will automatically use the input mask.
Toggle Switch	Is Checked	To set an initial value using the GetSharedVariable function, use True (checked) or False (unchecked). This is also how the function will return the current state after a user has interacted with the check box.

Returning shared variable values using GetSharedVariable

The GetSharedVariable function returns the current value of a named shared variable. If the variable does not already have a value, the GetSharedVariable function can also be used to set an initial value for the variable.

The GetSharedVariable function takes the following parameters:

When the GetSharedVariable function is calculated, Axiom Software checks the list of variables for the shared form instance. If the variable has a value, the function returns that value. If the variable does not currently have a value, the value of the variable is set to whatever is defined in the DefaultValue parameter for the function. That value persists as the variable value until the value is changed by either a SetSharedVariable function or by an interactive component that is configured to use the shared variable. The value can be set by any form in the shared form instance.

For example, imagine the following function:

When the function is calculated, Axiom Software checks the shared list of variables stored in memory. If the variable ReqType currently has a value—for example, "Facilities"—then the function will return that value and the default value in the function is ignored. If the variable ReqType does not currently have a value, then the value is set to "Standard" and the function will return that value. If the function is edited so that the DefaultValue parameter value is now "General", the function will continue to return "Standard" because the variable already has a value. All GetSharedVariable functions in the shared form instance for variable ReqType will return "Standard" until the variable value is changed by a SetSharedVariable function or by an interactive component.

Some examples of how the GetSharedVariable function could be used include:

• A plan file can use multiple embedded forms (utility files) to define the contents of the plan file. The parent plan file form can use SetSharedVariable to define a variable for the current plan code, and then the child forms can use GetSharedVariable to retrieve that value. Similar information, such as the plan code description and other attributes, can also be defined as variables in the parent form and then shared with all child forms.

• A form could be structured so that the parent form displays summary financial information, and the child forms are used to develop the detailed financial data. The summary in the parent form could display a running total that is impacted by the current inputs that the user is making in the child form. In order to dynamically update this running total without saving data to the database, the child form could use SetSharedVariable to define a variable for the current running total, and the parent form could use GetSharedVariable to retrieve that value.

When a variable value is set by any form in the shared instance, that value is immediately available to all other forms in the shared instance. There is no need to "push" or "apply" the new value to the other forms. However, in order for the GetSharedVariable function to return the new value, the function must calculate. This means that an update must be triggered for the form in order to reflect any changed variable value. You may need to configure the form as appropriate to force this update to occur. For example, if you are using a Menu component to switch between various child forms, you may need to enable [ForceRefresh] for a child form in order to update it for changed variable values. For more information on how form update behavior applies to embedded forms, see Form session and update behavior for embedded forms.

Using the Apply Shared Variables command

You can use the Apply Shared Variables command to set values for one or more shared variables as needed. Typically this is used to set variables in conjunction with another action.

For example, you may have a grid in an Axiom form where each row shows information about a particular department. You want the user to click a button on the row to open a dialog panel that shows more details about the current department. In order to do this, you need a way to filter the contents of the dialog panel by the department for the current row. You can use an Apply Shared Variables command on the button to set the value of variable Dept to the value for the current row.

For more information, see Apply Shared Variables command.