AX2690

Task pane design considerations

Keep in mind the following design considerations when creating task panes.

Creating task panes with multiple sections

All top-level items in a task pane are automatically section headers. These items display using a gray header bar, and can be expanded and collapsed (by default, they display expanded).

If the task pane only needs one section, then the task pane should be created so that all items are children of a single top-level item. The following screenshot shows an open task pane with one header side-by-side with the associated view in the editor.

If the task pane needs multiple sections, then you can add multiple top-level items, and then add child items to each section as needed. The following screenshot shows an open task pane with multiple headers side-by-side with the associated view in the editor.

Shortcuts on items with children

Shortcuts cannot be defined on items in a task pane that have child items. When an item has child items, double-clicking the parent item expands or collapses the item—therefore, there is no way to launch the associated shortcut for that item.

The task pane editor does not prevent saving a task pane with this configuration, however, it does display a validation message informing you that an item cannot have both a shortcut and child items.

If you want to link to a file or feature and include associated instructional text, the shortcut should be defined in the child items, not on the parent item. For example:

In this example, the parent item serves as a statement of what to do, followed by instructional text and then the link to the import.

Forcing display of an item

By default, if an item in a task pane links to a file or feature, and the user viewing the task pane does not have access to that file or feature, then the item does not display in the task pane for that user. This allows you to create task panes that are dynamic by user—you can include a full set of items in the task pane and users will only see the items that apply to them.

Items in a task pane are also hidden if they do not apply to the current context. For example, an item that links to the Add Rows command is hidden by default if the current file is a report, because that command cannot be used in reports.

However in some cases you may want all items in a task pane to display, regardless of whether a user has rights to the items, and regardless of whether the item applies to the current context. For example, you may be creating a task pane that documents a particular process, and all of the process steps are numbered. If a user does not have rights to the file linked in step 5, then step 5 will be omitted from the task pane. Although the auto-numbering will be adjusted for the omitted item, you may prefer to include the item in the task pane anyway for one or more of the following reasons:

• The omitted step may be required, and the user needs to know that it is there and that they cannot perform it as is. Perhaps the user needs to wait for someone else to perform that step, or maybe the security settings have been made in error and the user should have access to that file.
• The omitted step may be optional, but you still want the user to see its place in the overall process. Users with the appropriate rights can perform the step, and users without rights can simply move on to the next step.

To force an item to display in a task pane regardless of security settings or current context, enable Show restricted item in the Display Settings for the item. This must be selected on a per item basis.

If this option is selected and a user does not have access to the linked item, or the item is not applicable to the current context, then the item is grayed out in the task pane.

Displaying child items inline

If an item has child items, you can choose to display those items inline (at the level of the parent item), omitting the display of the parent item. To do this, you must enable Display child items inline for the parent item.

This behavior applies even when the child items are not defined in the task pane structure, but are dynamically generated as part of the parent item. For example, if you link a task pane item to a report folder, the folder is the parent and the files in the folder are the child items, even though the child items aren't technically defined in the task pane structure.

In this example task pane structure, the task pane item links to a report folder, and the item is configured to display child items inline:

The following screenshots show the difference in how this item displays, depending on whether Display child items inline is enabled.

Display child items inline: Enabled

Display child items inline: Disabled

In the first example, the parent item does not display, and instead the child items display at the same level of the parent item. In the second example, the child items display as normal under the parent item.

This setting is also useful when including pre-built feature controls in a custom task pane, such as the Axiom Explorer Tree View. If you link a task pane item to the control, then by default the control will display as a child item underneath the parent item. If instead you want the item to display directly within the task pane, omitting the parent item, then select Display child items inline.

For example, the following task pane item is linked to the Axiom Explorer Tree View control, configured to show only the My Files section and configured to display child items inline.

The following screenshots show the difference in how this item displays, depending on whether Display child items inline is enabled.

Display child items inline: Enabled

Display child items inline: Disabled

In the first example, the My Files control is displayed directly within the task pane, omitting the parent item. This is most often the preferred way to display a pre-built feature control. In the second example, the My Files control is displayed underneath the parent item, which results in a duplicate header.

Embedding a task pane within another task pane

It is possible to create "nested" task panes, where the content from one task pane displays within another task pane. This is accomplished by using the shortcut property Embed list items when linking to the task pane, and then optionally also enabling Display child items inline for the linked item.

NOTE: If Embed list items is enabled, then the contents of the embedded task pane are treated as if they are part of the current task pane. Axiom Software does not make a separate security check to see if the user has permission to access the embedded file—the user's permission to the current file is all that matters. However, security permissions will be applied to the contents of the embedded task pane as normal.

For example, imagine that you have a task pane, and you want to create a second task pane that has the same content as the first task pane plus some additional items. If you link to the first task pane from the second task pane, by default the first task pane will display as a file within the second task pane, and users can double-click the file to open the first task pane. But if you instead enable Embed list items, then the contents of the first task pane will display embedded within the second task pane.

At this point the items display as a collapsible node, with the name of the first task pane as the "parent" item and the contents of the first task pane as child items.

If instead you want the contents of the first task pane to display inline within the second task pane (as if they were defined directly within the second task pane), then you must also enable Display child items inline for the linked item in the second task pane.

NOTE: If you embed a task pane in another task pane, and you plan to assign the "parent" task pane to users as a startup file, keep in mind that users must have explicit permission to the embedded task pane in order for it to display in the startup task pane. The implicit permission that results from startup file assignment only applies to the parent task pane.