3D PLM Enterprise Architecture

What is the Administration Tool

The Administration Tool is a common command that centralizes all administration commands (i.e. commands that configure the application settings).

As you can see, the Administration Tool, is displayed in two parts:

• The Category tree: organizes and classifies administration commands in a logical way.
• The Option Area: a zone that displays the administration command related to the selected node in the category tree.

From a development point of view, the Administration Tool takes charge of the OK/Cancel lifecycle, and the administration commands code should never worry about this.

For any application, it is possible to create one or more administration commands, and define the category path where it will be accessed. This articles explains how.

It is also possible to associate an administration command to a JDialog command (ex: "People & Organization administration" may be associated to a "Project Management" command). This is explained at the end of this article.

[Top]

How to create an administration command?

An administration command is a standard JDialog command, except that it's root component has to be an Option Panel (CATOptionPanel).

Assuming all administration datas are stored in the settings (CATSetting), the administration tool manages a centralized setting repository object that is accessible through the option panel object. The command controller can retrieve it with CATOptionPanel.getSetting( );

This setting repository object is initialized and available for the application right after the option panel fires an Initialize notification (onInitialize).

Here are main methods of CATOptionPanel class:

public class CATOptionPanel extends CATDialog
{
	/**
	 * Returns the 'Initialize' notification (fired after the OptionPanel has been initialized with the setting object)
	 */
	public CATNotification getInitializeNotification();

	/**
	 * Returns the setting object (managed by Administration Tool)
	 */
	public CATSetting getSetting()

}

Basic rules for programming an administration command:

• You don't need to manage the setting creation and flush lifecycle: just use the one provided by the CATOptionPanel widget
• You don't have to instantiate and take car of OK and Cancel buttons (they are handled by the Administration Tool).
• The OK button is enabled as soon as you modify a setting and the flush is automatic when the user clicks the OK button.

Sample: MyAdminCommand.XMLDlg file:

<?xml version="1.0"?>
<OptionPanel Name="option" Attribute="_Option" onInitialize="onInitialize" Controller="com.dassault_systemes.myadmin.MyAdminCommand">
  <Frame Name="f" DefaultButton="Change">
    <TextField Name="Field" Attribute="_TextField"/>
    <Button Name="Change" onButtonActivated="onUserChangedValue"/>
    [...]
  </Frame>
</OptionPanel> 

As you can see:

• The root widget is an OptionPanel
• The controller holds a reference to the option panel widget (_Option)
• The controller registers to the onInitialize notification (instead of onCreate)

Here is a controller sample: MyAdminCommand.java

package com.dassault_systemes.myadmin;

import com.dassault_systemes.catjdialog.CATOptionPanel;
import com.dassault_systemes.catjsystem.CATSetting;

public class MyAdminCommand
{
	public CATOptionPanel _Option;
	public CATTextField _Textfield;
	[...]

	/**
	 * onInitialize callback: initialize the user interface from the settings
	 */
	public void onIntialize(CATDialog iDialog, CATNotification iNotification, Object iData)
	{

	    try

	    {

	        // --- retrieve settings

	        CATSetting setting = _Option.getSetting();

	        // --- initialize the User Interface from the settings

	        _Textfield.setText(setting.getString("MyAdmin", "MyStringValue", "" ) );

	        [...]

	    }

	    catch( Exception e )

	    {

	        [...]

	    }
	}
	/**

	 * When the user modifies a value, store it in the settings.

	 * Note: right after the first stored value, the OK button is enabled, and when the user presses it, 

	 * all modified values are flushed into to database.
	 */
	public void onUserChangedValue(CATDialog iDialog, CATNotification iNotification, Object iData)
	{

	    // --- retrieve settings

	    CATSetting setting = _Option.getSetting();

	    // --- store the new value in the settings

	    setting.setString("MyAdmin", "MyStringValue", _Textfield.getText());

	}
} 

Note: the setting object is always retrieved with _Option.getSetting(). This way, the controller is fully stateless.

[Top]

How to add an administration command to the Administration Tool?

Once the administration command is written, you still have to register it to the Administration Tool (and declare it's category path). This is done through 'XMLCmdIndex' files, that must be created in [myFrameWork]/CNext/resources/command/[index file name].XMLCmdIndex

Sample: MyAppCmdIndex.XMLCmdIndex file:

<?xml version="1.0"?>
<CmdIndex>
  <!-- declaration of the administration command for administrator -->
  <Option Name="MyAppAdminCommand" CategoryPath="/Admin/MyAppAdmin"/> Authorized="Admin" Icon="MyAppAdmin.gif" HelpURI="/online/ptlad_O2/myadmin.htm"
  <!-- declaration of an option panel that can be customized by every user -->
  <Option Name="MyAppPreferences" CategoryPath="/MyApplicationRoot/MyPrefs"/> Icon="MyAppPrefs.gif" HelpURI="/online/ptlad_O2/myprefs.htm"
  [...]
</CmdIndex>

Attributes of Option tag are:

• Name (mandatory): the Name of the XMLDlg defining the administration command (root widget is expected to be an OptionPanel).

• CategoryPath (mandatory): gives the category path where the administration command is accessible inn the Administration Tool.

• Authorized (optional): defines whether the administration command is reserved for administrators or for all users. Supported values are 'Admin' or 'All'. Default value is 'All'.

• Icon (optional): the icon filename that will be used in the category path for representing the administration command (icons are found in the resources/graphic directory in the runtime view).

• HelpURI (optional): the relative path to the help for the administration command (a link appears when it is set).

Localized values of the category path are stored in a CATNls file associated to the XMLCmdIndex file.

Sample: MyAppCmdIndex.CATNls file:

// --- Catalog file for MyAppCmdIndex.XMLCmdIndex
// --- contains NLS names for Category tree

Category.Admin= "Administration";
Category.MyAppAdmin= "Buzz 2000 Administration";
Category.MyApplicationRoot= "Buzz 2000";
Category.MyPrefs= "User Preferences";

[Top]

Short guide to create  administration commands:

1. The XMLDlg file:

• The root element is an OptionPanel
• In order to initialize the user interface from settings, you need to register to onInitialize notification (instead of onCreate)

2. In your controller:

• Access the setting object from the CATOptionPanel
• Don't try to enable the OK button by yourself: this is done automatically as soon as you store a new value in the settings
• Don't try to flush the setting values by yourself: this is handled by the Administration Tool infrastructure, based on the OK/Cancel buttons

3. The XMLCmdIndex:

• Declare your administration command and it's related category path
• Don't forget to create associated CATNls files containing localized category path node names

[Top]

How to associate an administration command to a JDialog command?

Associating an administration command to a JDialog command adds an icon to the portlet titlebar that allows direct access to the administration tool on the right administration command.

This association is done in 'XMLCmdIndex' files.

Sample:

<?xml version="1.0"?>

<CmdIndex>

  <!-- declares the administration command "MyAdmin" -->

  <Option Name="MyAdmin" [...]/>

  [...]

  <!-- declares the JDialog command "MyCommand" and associates it with the administration command "MyAdmin" -->

  <Command Name="MyCommand" ... Option="MyAdmin"/>

  [...]

</CmdIndex> 

[Top]

History

Copyright © 2000, Dassault Systèmes. All rights reserved.