AX1294

Using an Axiom form as a task pane

Axiom forms can be used as task panes in the Axiom Software Excel Client or Windows Client. When used as a task pane, the Axiom form opens within the Axiom Assistant area, and can be used to impact the active spreadsheet file.

There are two ways that an Axiom form can be used as a task pane:

You can associate the Axiom form with a particular Axiom file using the Associated Task Pane setting on the Control Sheet. When the spreadsheet file is opened, the associated Axiom form document will automatically open as a task pane in the Axiom Assistant area. This approach is recommended when the purpose of the task pane is to perform actions on that particular spreadsheet file.
You can embed the Axiom form within a custom task pane, using the command Show Form. When using this approach, the task pane can be opened in any way that a normal custom task pane can be opened. For example, the task pane can be assigned to open automatically at startup, or it can be opened on demand from the Task Panes Library. This approach is recommended when the purpose of the task pane is more general, and does not depend on the presence of any particular file.

NOTE: Regardless of which configuration you use, any user whom you want to use the task pane must have at least read-only security permission to the Axiom form. There is no configuration that implicitly grants access to the Axiom form when it is used as a task pane. Even if the form is embedded in a custom task pane and the custom task pane is specified as a startup file, the user still needs security access to the Axiom form (though they do not need access to the task pane file).

Comparison of using Axiom forms versus regular custom task panes

The primary reason to use an Axiom form over a regular custom task pane is the ability to gather inputs from the user and then pass those values from the Axiom form to the active spreadsheet file (using the "form state" feature). Custom task panes cannot do this.

For example, you could create a form task pane to be used as a persistent refresh assistant for the current file. The user could make selections in the task pane and apply them to the current file using buttons in the task pane.

However, there are other advantages to using an Axiom form as a task pane, even if you do not need to pass values to the active spreadsheet file. For example, the appearance of the form task pane is completely customizable—Axiom forms have much more design flexibility than custom task panes.

On the other hand, Axiom forms do not support the full range of commands that custom task panes support. If you want to use a task pane as an alternative "menu" where users can access various Axiom Software features, then you should use a custom task pane.

Designing an Axiom form to be used as a task pane

The Axiom form to be used as a task pane should be configured as follows:

If you want the task pane to interact with the active client spreadsheet, then you can configure the file to use form state and/or various commands that execute on the active spreadsheet file.
- For more information on using form state, see Passing values between an Axiom form and the active client spreadsheet (form state).
- For more information on available commands, see Executing commands on the active client spreadsheet from an Axiom form.
The Canvas Size of the form (width x height) should be set to an appropriate size for a task pane. A good starting point is 300 x 800. Generally speaking, task panes should be tall and thin. You can use dynamic sizing and positioning options for components as appropriate, so that the form will adjust to the user's task pane area.

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 a Formatted Grid component is used, and if the task pane may be associated with multiple files that could be open at the same time, then the number of rows and columns in the grid must remain constant. If the number of rows or columns changes as a user moves from file to file, then the update and refresh behavior of the Axiom form may not work as expected.

The form size 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.

When deciding where to save the file and what to name it, keep in mind that another file may require the continued presence of this file (if using the Associated Task Pane option). If the Axiom form is deleted, moved, or renamed, then the file that is configured to use the Axiom form as an associated task pane may no longer work as expected. 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.

Embedding a form within a custom task pane

Use the Show Form command in a custom task pane to embed the contents of an Axiom form within a custom task pane. This allows the Axiom form to be used in any context that a custom task pane can be used—such as a startup file.

It is required to configure the task pane so that the Show Form command is the only item in the task pane, and to enable Display child items inline for that item. This means that when the task pane is opened, the designated Axiom form is displayed as the entire contents of the task pane.

Recommended configuration for using Show Form

For more information, see Show Form command and Managing task panes.

Associating a form task pane with a particular file

To associate a task pane with a particular Axiom file, you must complete the Associated Task Pane setting on the Control Sheet of the spreadsheet file. When the Axiom file is opened, the associated task pane is also automatically opened and will remain available for use while the file remains open.

For example, if you want to associate a form task pane with a particular report, you would enter the file path to the form in the Associated Task Pane setting for the report:

\Axiom\Reports Library\Forms\MyTaskPane.xlsx

When the report is opened, the form-enabled file named MyTaskPane.xlsx is opened in the Axiom Assistant area as a task pane, and that task pane remains linked to the report file.

Alternatively, you can use document shortcut syntax to specify the form. When using a document shortcut, you can add a parameter to specify an alternate tab name for the form. If specified, this tab name will be used instead of the file name. For example:

document://\Axiom\Reports Library\Forms\MyTaskPane.xlsx?AxiomTabName=MyTab

To create the document shortcut syntax, take the normal file path and then add the text document:// to the front of it. To use the optional tab name parameter, append the text ?AxiomTabName=Name to the end of the shortcut.

For more information on using this feature, see Associating a task pane with a particular file.

NOTE: If multiple open files have the same associated task pane, then each open file will have its own instance of the Axiom form. Each instance will remain in sync with its own file.