Best practices for improving tasks

Provide a 24-pixel icon

Tasks are encouraged to provide a 24-pixel icon.  If a task does not provide a 24-pixel icon, its 16-pixel icon will be used.  This looks a little small on the toolbar.

Consider a hypothetical task called Xyz.  In XyzTask.properties, an Icon.Toolbar line should be added if it is not already present.  For example:

Icon.Toolbar = /com/ibm/sysmgt/xyz/images/xyz24.gif

Of course, the xyz24.gif file must be present in the specified location.

Only the top-level (null-parent) tasks need 24-pixel icons.

Specify the overview help topic

Tasks are encouraged to specify which help topic is the overview, either by providing the Director.overview key, or by putting the topic first in the properties file.

Again in XyzTask.properties, a helpTopicsMapping line must be added if one is not already present.  For example:

	helpTopicsMapping = /doc/en/ibm/sysmgt/xyz/HelpTopicsMapping

If helpTopicsMapping is not given in XyzTask.properties, then the task will not have a “help” menu item  to give an overview.

In the HelpTopicsMapping.properties file, a Director.overview line should be added.  For example:

Director.overview=ibm/sysmgt/xyz/Overview.html

If the Director.overview key is missing, then the first line (after any comments) is assumed to be the help topic that gives an overview of the task.  This is already the case for most tasks.

Customize the task menu

It is a best practice to make the task menu more readable by wording the items as verbs instead of nouns.  For example, “Inventory” is better worded as “View Inventory” in the tasks menu.

This section shows how to customize the text in the task menus with minimal impact on the Task pane.  The improvements to the task menus will also apply to task buttons in the toolbar. 

The modifications will mostly involve changes to properties files.  Of course there will also be new lines inserted into resource bundles.  In some cases, a minor code change is necessary.

All of the recommendations in this section are backward-compatible to 4.2.  An extension can implement these best practices in 4.2, even though many of them will not be visible until 5.1.

None of these recommendations are requirements.  All of the function in your extension will be exposed in the new user interface using the task menu, without changing the extension in any way.  But the task menu offers an opportunity for improved usability.


Subtask is double-click only

If a subtask is double-click only and has no menu, then simply add one.  In the following example, the last line is added in order to place text in the menu:

	Subtask.0.ID            = NITEdit
	Subtask.0.Context       = interactive:true | client:start | server:true | targeted:multi
	Subtask.0.Actions       = double-click
	Subtask.0.Menu          = Create...,101

If the subtask already has a menu, but it is inappropriate (perhaps it just reuses text from another subtask), then give it new menu text.

This replaces the default “Open…” item in the Task menu with a more specific verb, such as “Create…” or “Edit…”  It prevents the name of the Task from being prepended, e.g. “Process Monitor: Open…” becomes simply “Create…”, and Process Monitor is implied by the context.

In this example, right-clicking the task in the tasks pane still shows the “Open…” item instead of “Create…”.  If you want to see “Create” instead of “Open” in the task pane menu, add the following line:

	Subtask.0.MenuLocation = TaskIcon

Make sure that the menu item’s sort order (101 in this case) places the menu at the top; otherwise you will see both “Open” and “Create”.


Subtask is drag-and-drop only

If a subtask is drag-and-drop only and has no menu, then simply add one.  In the following example, the last line is added in order to place text in the menu:

	Subtask.0.ID = Run
	Subtask.0.Context = interactive:false | client:ignore | server:true | targeted:multi
	Subtask.0.Actions = drag-drop-multi
	Subtask.0.Menu = Remove Process Monitors from {1},100

If the subtask already has a menu, but it is inappropriate (perhaps it just reuses text from another subtask), then give it new menu text.  Hint: “Apply to {1}” is a good general-purpose drag-and-drop menu when the menu’s parent tells what is being applied.

Subtask is drag-and-drop and double-click

In general, be cautious about using the same subtask for more than one action.  For example, think carefully about using a single subtask to handle both double-click and drag-and-drop.  In the new console, this subtask will only have one menu item, and it will change depending on whether or not a target is selected.  you should only share a subtask between drag-and-drop and double-click if the user would not need the double-click function except as a “last resort” when there is no target.  If the user sometimes needs access to the double-click function, then give it a separate subtask.  As we will see, this is a trivial change.

Even if drag-and-drop and double-click have separate subtasks, the task menu will show only one.  It will show the drag-drop subtask if a target is selected, or only the double-click subtask if no target is selected.  To make both show up, the double-click subtask should have:

Subtask.0.MenuLocation = TaskIcon

The double-click task should come first, that is, be Subtask.0, and the drag-and-drop task should come second.

Subtask is drag-and-drop and object icon

If a single subtask is used for both drag-and-drop and the object icon menu, then you will need to break it apart into two tasks.

In the task properties file:

Old

New

Subtask.0.ID = ProcessMgmt

Subtask.0.ID = ProcessMgmtDnD

Subtask.1.ID = ProcessMgmt

Subtask.0.MenuLocation = ObjectIcon

Subtask.1.MenuLocation = ObjectIcon

Subtask.0.Menu = ProcManTitle,220

Subtask.0.Menu = Manage {1},220

Subtask.1.Menu = ProcManTitle,220

Subtask.0.Context = interactive:true | client:start | targeted:one

Subtask.0.Context = interactive:true | client:start | targeted:one

Subtask.1.Context = interactive:true | client:start | targeted:one

Subtask.0.Actions = drag-drop

Subtask.0.Actions = drag-drop

Notice the use of the {1} parameter in the menu text.  In menu text, {0} is replaced by the name of the subtask, and {1} is replaced by the name of the target.  (Of course, in a real application, the menu text would actually be placed in a resource bundle.)

In the code, when testing for the “ProcessMgt” ID, you must now test for both “ProcessMgt” and “ProcessMgtDnD”.  For example:


if (ta.getSubtask().getID().equals("ProcessMgmt")) {

becomes:


if (ta.getSubtask().getID().equals("ProcessMgmt")
  || ta.getSubtask().getID().equals("ProcessMgmtDnD")) {

Lone child task needs own submenu

If a child task has no subtasks or children, then it is usually pulled upward into the parent menu.  This avoids menus with only one item.

However, in some cases you might want a child tasks to appear alone in a single-item menu.  This is commonly the case when the child task has the ability to create siblings, so that it might not be alone in the future.  It is then best for the child task to not be absorbed into the parent menu, so that the structure of the menu does not change when more children are added.

To cause a task to have its own menu, use the following line in the properties file:

	TaskHasOwnMenu = true

Additional changes to consider

All existing extensions will still work in IBM Director 5.1.  However, as extensions are updated, the following changes should be considered.