AX1315

Passing values from one file to another using document variables

When opening one Axiom file from another Axiom file, you can pass values to the target file using document variables. For example, you may want to set certain values in the first file, then pass those values to the target file to impact the data queries in the target file. This applies to the following functions:

• GetDocument
• GetFormDocumentURL
• GetFormDocumentLinkTag

The GetDocument function is used when you want to open a new spreadsheet Axiom file from within another spreadsheet Axiom file. In this case, the user double-clicks the function in the starting file to open the target file.

The other two functions are used when you want to open a new Axiom form from within another Axiom form.

• The GetFormDocumentURL function can be used to generate a URL to another Axiom form, and then that URL can be used in a Hyperlink component or in an HREF tag for a Formatted Grid component.
• The GetFormDocumentLinkTag function can be used to generate a fully constructed HREF tag for a Formatted Grid component. The user clicks the resulting hyperlink in the starting form to open the target form.

The ability to pass values to the target file is set up as follows:

• In the starting file, use the Variables parameter of the function to pass variable/value pairs to the target file.
• In the target file, use the GetDocumentInfo function to return the value for each variable that was passed to the file. You can then reference these values to impact the data query.

For example, imagine that you want to determine a region within the starting file. When the function is used to open the target file, you want to pass the region to the target file and filter the data queries to show only data for that region. The following discussion uses this example to illustrate how to set up this relationship between files. This example uses the GetDocument function, but the same principles apply to the other two functions.

Setting up the starting file

In the starting file, you must define the document variable and the value that you want to pass to the target file. In this example, the variable/value pair is as follows:

You can use any method that you want to determine the region value. For example, you might use formulas to automatically determine the appropriate region. Or you might ask the user to select a region from a drop-down list.

Once the region value is determined, you must include the variable/value pair in the GetDocument function. For example, imagine that the region value is stored in cell B2 of the Variable sheet. The GetDocument function might look as follows:

You can include multiple variable/value pairs in the Variables parameter, separated by semicolons. For example, if we wanted to also pass a VP name, the GetDocument function might look as follows:

When the user double-clicks on the GetDocument function, the target file is opened and the variable values are passed to that file.

Setting up the target file

In the target file, you must use the GetDocumentInfo function to return the variable values that were passed to the file by the GetDocument function. For example, to return the Region value you would use a function like the following:

You would set up the queries in this file so that they are filtered by the value returned by the GetDocumentInfo function. In most cases, you would also want to enable "refresh on open" (so that the queries are run when the file is opened and the filter is applied), and set up dynamic headers that reference the region value.

Keep in mind that until a variable value is passed to the file using the GetDocument function, the GetDocumentInfo function will return blank. If you need the queries in this file to work even when no variable value has been passed, you have two options:

• You can set up the formula for the query filter so that a different filter (or no filter) is used if the GetDocumentInfo function returns blank.
• You can define a default value for the variable within the GetDocumentInfo function. The function will then return that default value until a new value is passed using the GetDocument function.

The default value is the third parameter of the GetDocumentInfo function. For example, a default region value could be set within the function as follows: