# Adding Support for Preferences

You can create a new properties panels that appear in a Properties dialog through a properties extension. You can also use the preferences-related API to store and access information that your extension needs but may not expose to the user as a properties panel.

For example, imagine that you've created an extension to provide support for an external tool, such as a source control manager. You'd likely want to provide a preferences extension also so that users can set the path to the source control server, user name and password, and so on.

The following illustrates a properties panel created by the PopupAction sample extension.

Note: WebLogic Workshop uses the terms "properties" and "preferences" in various contexts, and it can be confusing at first. For extensions that support application, project, and IDE properties, they are exposed as "properties" in the user interface (through panels in the Properties dialog), but defined as preferences extensions. This is reflected in the extension XML, which uses terms such as "project-preferences". In addition, you should not confuse preferences as they're referred to here the the properties exposed by the IDE and described in the PropertyListener sample project.

## Building Preferences Extensions

To build a preferences extension, you:

- Write an extension.xml that specifies whether the properties panels to add are scoped to a project, application, and/or IDE. This file also specifies which classes in the extension are to be used for the panels UI and logic.
- Write Java classes that support the preference by providing the panel's user interface by implementing the required interfaces.

### Scope for Properties

WebLogic Workshop provides dialogs for setting properties scoped to the applications, projects, and the IDE. The scope of the properties you're handling impacts how you define and handle them. For example, project properties should be defined as such in the extension XML and handled through an instance of the IProject interface. For more information about these differences, see the following sections.

## Extension XML for Preferences

The extension XML for specifying properties panels is among the simplest you'll write. One of three elements — <ide-preferences>, <workspace-preferences>, and <project-preferences> — sets the scope for the properties the panel will expose. In the <panel> element, you specify the label that should be used in the left side of the Properties dialog. You also tell the IDE what extension class to use for the panel's logic. The class you specify should extend JPanel and implement IPropertyPanel, as described in Implementing Properties Handling Logic, below.

The following example shows the extension XML for a properties panel scoped to an application (also known as a workspace).

    <extension-xml id="urn:com-bea-ide:settings">
        <workspace-preferences>
            <panel label="PHP" class="com.myco.properties.PHPPanel"/>
        </workspace-preferences>
    </extension-xml>

For reference information on extension XML for properties extensions, see Preferences Extension XML Reference.

## Implementing Properties Handling Logic

Your properties panel will implement the IPropertyPanel interface or an interface that extends it. This interface provides methods through which you can interact with the IDE to retrieved saved values, validate and store changed values, and handle the user's canceling the dialog.

### Implementing IPropertyPanel

Your extension class should extend JPanel and implement IPropertyPanel (or an interface that extends it, such as IProjectPropertyPanel). The constructor is a good place to assemble the user interface. The IDE calls your implementation of the IPropertyPanel interface's loadProperties method. Here, your code retrieves saved property values and puts the values into the user interface components that will display them.

If the user clicks OK in the properties dialog to save the values, the IDE calls your implementation of the validateEntries method. Your code should use this method to retrieve values from the user interface components and determine if they're suitable as values for your properties. If they are, you should return true from the method. If they aren't, you should display an error message (a message that helps the user figure out what they need to do to correct the situation), then return false from the method. The user will not be able to dismiss the dialog by clicking OK until you return true from this method.

If your code returns true from the validateEntries method, the IDE will call your implementation of the storeProperties method. Here, your code should store values retrieved from the panel's user interface components.

If the user clicks the Cancel button in the dialog instead of OK, then the IDE will call your implementation of the cancel method. Here, you can release any resources you may have acquired.

### Accessing and Saving Preference Values

Your implementation of the loadProperties method should retrieve saved values and display them in your panel's user interface. While you don't need to use WebLogic Workshop's preferences storage mechanism, that API does provide a convenient way for you to set and get property values.

WebLogic Workshop provides a scope-specific API for storing and retrieving value sets in the form of java.util.prefs.Preferences instances. You can use this API to retrieve a Preferences instance that contains existing stored values, then use the instance to get and set the values in your panel's code. Depending on the scope of your properties panel, you can use one of the following to retrieve the preferences instance:

- IProject for project properties.
- IWorkspace for application properties.
- Application.I for IDE properties.

Each of these extends IPreferencesSupport. When using one of these APIs you'll typically call either the systemNodeForPackage or userNodeForPackage method to retrieve a Preferences instance through which to access and store property values. You'll pass to the method a Class representing your properties panel. You store and retrieve individual properties through get and put methods using key/value pairs, where the key is some unique value representing the property.

For example, to get a property value:

    private IProject m_project;
    Preferences prefs = m_project.systemNodeForPackage(FTPPrefsPanel.class);
    String hostname = prefs.get(FTPSettings.HOSTNAME, ""));

Related Topics

PopupAction Sample

Preferences Extension XML Reference