AX1295

Associating a task pane with a particular file

You can associate a task pane with a particular file, so that the task pane automatically opens when that file is opened, and remains available for use while the file remains open.

For example, you might want to allow users to change refresh options for a report within a task pane instead of using a refresh dialog. Or you might design a task pane to assist users in completing their plan files, and you want that task pane to be automatically available when users are working in a plan file.

The associated task pane can be a custom task pane in the Task Panes Library, or it can be an Axiom form that has been designed for use as a task pane. For more information about designing an Axiom form for use as a task pane, see Using an Axiom form as a task pane.

Specifying the associated task pane for a file

To associate a task pane with a file, use the Associated Task Pane setting within the file. This setting is located on the Control Sheet, in the Workbook Options section:

Specify the full path and file name to one of the following:

• A custom task pane file in the Task Panes Library (AXL file)
• A form-enabled file, where the form has been designed for use as a task pane

For example:

To easily obtain the full path for a file, navigate to that file in the Explorer task pane, then right-click and select Copy document path to clipboard. You can then paste the value into the cell.

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

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.

The next time you open the document after saving, the entry will be automatically converted into a system-managed document shortcut (you can tell the difference by the presence of a _tid parameter on the end of the shortcut). If you need to change the entry to point to a different document, or to change the tab name, simply enter the path or document shortcut as you would have originally, and it will be converted again when you save the file.

NOTE: The user must have at least read-only permission to the associated task pane file in order to open it. If the user does not have access to the file then the task pane will not open and no error will display. If desired, when configuring security access to the task pane you can clear the Show in Explorer option so that the task pane does not display in the Explorer task pane or other "Explorer views."

If the Axiom file is form-enabled, then the associated task pane does not apply when the file is open as an Axiom form, with one exception: if the associated task pane is being used to define navigation links for the form, those links will display in the Navigation panel of the Web Client container. For more information, see Defining content for the Web Client Navigation panel.

Task pane behavior

When a task pane is associated with an Axiom spreadsheet file, the following behavior occurs:

• The task pane is opened automatically when a user opens the file, and the task pane is made active—meaning the task pane is selected and visible in the Axiom Assistant area. The tab name of the task pane is the file name, unless an alternate tab name has been specified using document reference syntax (see the previous section).

• The task pane is non-closeable. As long as the file is open, the task pane will remain open. The task pane will automatically close when the file is closed.

• The task pane is linked to the file. If the user moves to a different file, the task pane will hide, and if the user moves back to the file the task pane will become visible again.

The same task pane can be associated with multiple files. If a user has multiple files open with the same associated task pane, the behavior depends on whether the task pane is a custom task pane or an Axiom form.

• Axiom form: Each file has its own separate instance of the task pane (though only a single instance displays at any one time, depending on which file is the currently active file). Each instance maintains its own state for the active document.

• Custom task pane: One instance of the task pane is opened. This single instance remains linked to all associated files, but does not maintain a separate state for each file.