Creating console task extensions

This topic describes programming concepts and requirements to extend IBM Director to include user-defined console task extensions.

Subtopics

Related information

Related sample code

Understanding console tasks

As described in Understanding IBM Director tasks, IBM Director uses the concept of tasks as one if its primary extension points. Your organization might want to customize IBM Director with your own tasks, one or more of which might require interaction with the IBM Director administrators. While not all tasks require interaction with an IBM Director administrator, many do. To provide GUI interaction with a task extension, you must understand how IBM Director implements its interface to allow your organization to display information on the IBM Director console. 

The GUIs associated with tasks are referred to as Console Extensions. Console Extensions are expected to subclass TWGTaskFrame. The TWGTaskFrame super class provides a number of services to the Console Extension.

The IBM Director Management Console is written entirely in Java therefore you must use Java to extend the IBM Director interface. If your task has an interactive component, you need to specify the interface to IBM Director in your Task Properties file. In the Task Properties file, the GUI property contains a class attribute. You should set this attribute to the class name of the GUI you want to open. The class specified must extend TWGTaskFrame as is done in the console sample program.

NOTE: In this release of IBM Director, implementing TWGTaskFrameImplementor is no longer supported and GUIs must be created by extending TWGTaskFrame.

Understanding TWGTaskFrame

TWGTaskFrame is the base abstract class for all IBM Director top-level task frames. It provides the base implementation of the TWGTaskFrameImplementor interface for activating and deactivating a task frame. Your task console will look and act like the IBM Director product when you use TWGTaskFrame:

Each IBM Director task extension will design a unique image to represent its task. From this image an image set containing, at minimum, 16-point and 32-point gif files can be generated. If the task is to be displayed on a toolbar, a 24-point image and a 24-point rollover image will also be required. The images will be made available where appropriate to identify this task on the Console Extension frame, the main console, and/or in the help.

Panels displayed in the client area of this TWGTaskFrame must be constructed so that their presence in the product is both aesthetically and functionally seamless. Panels should have a clean, polished appearance and behave appropriately. See IBM Director Programming: Best Practices for more details on the layout of GUI Panels.

TWGTaskFrame services

TWGTaskFrame provides many services:

 
Figure 1. The IBM Director Console showing the Window menu. TWGTaskFrame provides a window management service. For more information about the IBM Director Console see the help topic on the Primary Console Window.

TWGTaskFrame objects will be notified when console preferences have been changed by the user, allowing the frame's components to update accordingly. Panels might be shadowed, colored or both:


Figure 2. Example of a TWGTaskFrame that has been notified to update after a user-preference change.

Constructing a TWGTaskFrame

In creating an IBM Director Console Extension you are required to:

Runtime considerations

TWGTaskFrame example

The Inventory Query Browser in Figure 3 is an example of a TWGTaskFrame object. Note that:


Figure 3. Inventory Query Browser as an example of a TWGTaskFrame.

Using TWGTaskFrame basic methods

Some of the benefits of using TWGTaskFrame have been explained in the preceding section; this section focuses on the use of the TWGTaskFrame class. You do not need to deal with the complexities of integrating your GUI with the implementation of the interface; you need only to provide a few simple methods to hook in your GUI code. This section describes those basic methods. Refer to com.tivoli.twg.console.TWGTaskFrame for complete information on all of the methods provided.

TWGTaskFrame()
There are two constructors provided for this class. When the constructor runs, a JFrame is created and all of the default color information is set up for this frame. The main constructor takes a boolean as a parameter. If true, the task frame is automatically created with a status panel. The status panel, by default, contains a status indicator as its left pane and a status text field as the right pane. If false, the task frame does not have a status panel.

Note:  The default constructor calls the main constructor with the createStatusPanel parameter set to false.

The syntax of the constructors is:

public TWGTaskFrame()
public TWGTaskFrame( boolean createStatusPanel )
pInit()
This method is called after your class is constructed. Implement your initialization routine for setting up non-GUI items here. Derived classes override this method to perform their initialization. If you need any information relating to this specific task activation, just call getTaskActivator to get the TWGTaskActivator object containing all of the information about the task activation related to this task frame. Return true to have the frame continue initialization and be displayed. Return false to prevent the frame from displaying and to end the task console (for instance, if initialization fails).

The syntax of the pInit() method is:

public boolean pInit()

buildView()
This method is called just before the frame is sized, positioned, and shown. Use this method to implement the GUI logic for the client area of your frame. Derived classes override this method and build their client window and all of the user interface controls (for example, entry fields, listboxes, buttons, and so on) required by their task's design. Return the top-level panel for your GUI which is then inserted into the client area of the frame.

The syntax of the buildView() method is:

public Container buildView()

Example:

public Container buildView()
{
  // Construct the top level client pane that all gui panes are
  // placed into.  Add a border and set the layout.
  JPanel clientPanel = new JPanel();
  clientPanel.setBorder( new EmptyBorder( 10, 10, 10, 10 ) );
  clientPanel.setLayout( new BorderLayout( 0, 10 ) );
  
  // Create a prompt and an entry field and add to client pane.
  JLabel prompt = new JLabel ( "Name:" );
  JTextField nameField = new JTextField( "", 24 );
  clientPanel.add( nameField, BorderLayout.CENTER );
  clientPanel.add( prompt, BorderLayout.WEST );

  return ( clientPanel );
}
getFrameSize()
This method is called by TWGTaskFrame to determine the initial size of the frame. You should override this method to provide a task frame size that is appropriate to your task console. The initial position is centered by default.

Note:  This method is only called the first time the task console is opened by a user. When the task console is closed, the size and position are cached away on a per user basis. Subsequent invocations of this task console use the cached size and position.

The syntax of the getFrameSize() method is:

public Dimension getFrameSize()

Example:

public Dimension getFrameSize()
{
  return new Dimension( 500, 300 );
}
verifyOnClose()
This method allows derived task frames to prompt the user if they should close or not. Derived classes override this method to check internal conditions and determine if it is okay to close and, if conditions are not right, to correct them or prompt the user for direction. For example, if a user requests a task console to close but has not yet saved information that was being editing, this method can be used to prompt the user whether to save the data before closing, to just close and lose the changes, or cancel and continue editing. Return true from this method to close the frame, otherwise return false to stop the frame from closing.

Note:  The task frame can only be stopped from closing if the user initiated the close of the task frame, that is, cancelType equals USER_REQUESTED_CLOSE. If the IBM Director Management Console is shutting down (MAIN_CONSOLE_SHUTDOWN), you cannot stop the frame from closing.

The syntax of the verifyOnClose() method is:

public boolean verifyOnClose( int cancelType )

pCleanUp()
This method allows derived task frame classes to clean up after themselves. Derived classes override this method to perform their cleanup. This method is called when the task frame is definitely closing. This means that any user verification that might have been implemented using verifyOnClose() has already completed and the user has indicated it is okay to close.

The syntax of the pCleanUp() method is:

public void pCleanUp()

Other useful TWGTaskFrame methods

Your task frame is now built but you are unclear on how to use the status panel or how to integrate your help information into IBM Director. This section describes some of the other methods in TWGTaskFrame that you can use (yes, you don't have to implement these, just use them) that are very beneficial in making your console task extension act like IBM Director console tasks. Refer to com.tivoli.twg.console.TWGTaskFrame for complete information on all of the methods provided.

getHelpContext()
TWGTaskFrame automatically creates a help context if the task specifies the helpTopicsMapping attribute in the task's property file. The helpTopicsMapping property specifies another property file that contains the mappings of help topics to HTML help files. A TWGTaskFrame instance only has to request its context using getHelpContext. It can then associate help with any of the components within the frame by using the addHelp() method on that context. If a helpTopicsMapping attribute is not specified, then no context is created and this method returns null. Refer to Integrating online help into IBM Director for complete information on using help contexts.

Note:  Help cannot be specified directly on the frame itself, but must be set on a component within the frame. Typically the client pane of the frame is used. If F1 is pressed while the frame containing that component has focus, help is then invoked. Additionally, if help is associated with a button or menu, pressing that button or selecting that menu invokes help as well.

The syntax of the getHelpContext() method is:

public TWGHelpContext getHelpContext()

Example:

getHelpContext().addHelp( clientPanel, "MyTaskConsole.mainHelpId" );
setStatusText()
Use this method to specify the text that should be displayed in the status field message area of the status panel. The message string to display in the status field is passed in.

The syntax of the setStatusText() method is:

public void setStatusText( String text )

Example:

setStatusText( "Searching..." );
startStatusIndicator()
Use this method to start animating the frames contained in the task frame's TWGStatusIndicator class. This method does nothing if your task frame does not contain a status indicator.

The syntax of the startStatusIndicator() method is:

public void startStatusIndicator()

stopStatusIndicator()
Use this method to stop animating the frames contained in the task frame's TWGStatusIndicator class. This method does nothing if your task frame does not contain a status indicator.

The syntax of the stopStatusIndicator() method is:

public void stopStatusIndicator()
getTaskFrameServiceNode()
Use this method to get a reference to the task frame's service node.  The service node can be used to send commands via the SendCommand and SendAsynchCommand methods.  See IBM Director Interprocess Communication for more information on ServiceNodes and sending commands.

The syntax of the getTaskFrameServiceNode() method is:

public final ServiceNode getTaskFrameServiceNode() throws ServiceNodeException

Integrating online help into IBM Director

IBM Director provides an on-line help browser that allows the user to request help when using a specific console or panel by pressing the F1 key or clicking on a help menu option or help button. If you are creating your own console task extensions, you might also want to provide help for your users that is integrated as part of the IBM Director help system. The TWGHelpContext class provides this integration. TWGHelpContext is used for all IBM Director help associations. A help context provides the base structure to allow task frames and other windows to associate a specific help panel with a specific frame window or dialog. A component creates an instance of this class for their use, passing in the instance of the main GUI and the name of the mapping file to use to locate the correct HTML file for a specific topic ID. This context is then used to associate help to components using the addHelp method. When help is invoked, the help context maps the component to its associated help using the mapping file and the current locale.

Sample Mapping File:


mainHelpTopicID         = BobCo/MyTask/mymainhelp.html
mySetupPanelHelpTopicID = BobCo/MyTask/mysetuphelp.html
myInputPanelHelpTopicID = BobCo/MyTask/myinputhelp.html

This section describes how to use TWGHelpContext to integrate help into your console task extensions.

TWGHelpContext()
If you are using TWGTaskFrame, you do not need this constructor. The help context is automatically created for you if you specified the helpTopicsMapping attribute in the property file of your task. The constructor creates a help instance that is used to bind and locate the correct help for a panel.

Each help instance has a mapping file that is used to map the help topic IDs to specific HTML files. This map finds the appropriate HTML file based on the topic ID requested and the current locale. Two parameters are passed to the constructor. The first is an instance of the main console controller. This instance can be obtained from the TWGTaskActivator object. Using this, IBM Director queries for the previous size and location used to display the help window. If null, then help is started using a default size each time. The second parameter is the name of the mapping file that contains the mappings of the topic IDs to the HTML file names. This file is in the same format as a regular properties file.

The syntax of the constructor is:

public TWGHelpContext( TWGMainGUI gui, String bundleName )

Example:

TWGHelpContext ivHelp = null;
String mapFile = getTaskActivator().getTask().getHelpTopicsMapping();
if (( mapFile != null ) && ( !mapFile.equals("")))
  ivHelp = new TWGHelpContext( getTaskActivator().getMainConsole(),
  							   mapFile );
addHelp()
Use this method to register a help listener to initiate a help event for this component. If the component specified is a button or a menu item, an action listener is registered with the component. This means a help event is generated if the button is pressed or if that menu item is selected. If the component is not a button or menu item, then it registers F1 as the key that initiates a help event if the component specified (or the window it is in) has the focus. The help event contains the topic ID as event data. Two parameters are passed to this method. The first is the component to register the help for. The second is the topic ID which identifies the help panel to display when help is requested. The topic ID must be found in the mapping file. If null is set, then dynamic help is set up for the component and the component is queried for the topic ID (and optionally a different mapping file) when help is requested. Refer to TWGDynamicHelp for information on this advanced topic.

The syntax of the addHelp() method is:

public void addHelp( JComponent comp, String topicID )

Example:

ivHelp.addHelp( clientPanel, "mainHelpTopicID" );
removeHelp()
Use this method to unregister the help listener that would initiate a help event if the component specified (or the window it is in) has the focus. This removes an action listener or keyboard action previously set up, depending on which kind of listener was originally set up. The only parameter passed into this method is the component to unregister the help from.

Note:  You should always remove any help associated with components as part of your cleanup when your task frame is going away.

The syntax of the removeHelp() method is:

public void removeHelp( JComponent comp )

Example:

ivHelp.removeHelp( clientPanel );