# Getting Started: IDE Extension Tutorial

This brief tutorial is designed to introduce the basics of building an IDE extension. In it, you'll learn a bit about the pieces of an IDE extension, including the extension.xml file and Java classes that make up a frame view extension. You'll also learn how to set up a Java project for building and debugging extensions.

The extension you build with this tutorial is very simple, so it's not surprising that a proportionately large amount of the tutorial is about getting set up -- creating the project, setting debugging properties, and so on. Needless to say, these are things that will come fairly easily after the first time around.

The tasks in this step are:

- To create a new Java project for extension code.
- To set up for debugging.
- To create an extension.xml file.
- To write the extension's Java code.

To Create a Java Project

You build IDE extensions in a Java project type.

1. Open the IdeDevKit sample application located here:

   BEA_HOME\weblogic81\samples\workshop\ExtensionDevKit\IdeDevKit\IdeDevKit.work

2. In the Application window, right-click the top folder, IdeDevKit, then click New -> Project.
3. In the New Project dialog, in the left pane, click All. In the right pane, click Java Project.
4. In the Project Name box, type FrameViewHello.
5. Click Create.

   WebLogic Workshop will display the FrameViewHello project in the IdeDevKit application. Now you will create folders for source files.

6. Right-click the FrameViewHello project folder, then click New -> Folder.
7. In the Create New Folder dialog, enter src as the new folder name.

   Next you'll tell the IDE to use this folder for Java sources. By default, the source path is set to the project's root. But if you leave it that way, you'll be unable to use the IDE to create a META-INF folder in the project to hold your extension.xml file ("META-INF" is illegal as a package name). You'll also add wlw-ide.jar to your classpath. It contains the classes and interfaces that make up the extension API. You're going to need those.

8. Right-click the FrameViewHello project folder, then click Properties.
9. Next to the Classpath box, click Add Jar and browse for the JAR file at:

   BEA_HOME\weblogic81\workshop\wlw-ide.jar

10. Select the JAR and click Select Jar.
11. Next to the Source path box, click Add Path and browse for the src folder you added earlier, probably at:

    BEA_HOME\weblogic81\samples\workshop\ExtensionDevKit\IdeDevKit\FrameViewHello\src

12. With the src folder selected, click Select Directory.
13. Click OK.

    Next you will create a META-INF folder for your extension.xml file.

14. Right-click the FrameViewHello project folder, then click New -> Folder.
15. In the Create New Folder dialog, enter META-INF as the new folder name.
16. Click OK.

To Set Up for Debugging

When debugging an IDE extension, you set up your build properties so that the extension build output is copied the WebLogic Workshop extensions folder. You set debugging properties so that a new instance of the IDE starts. This new instance examines the contents of the extensions folder, finds your extension JAR, and loads it with other extensions. This works iteratively so that each new build generates a new extension JAR which is read by the newly started IDE instance. Breakpoints you've set in the original instance are of course honored as you try out your extension in the second.

To set this up, you need to create a build.xml file in your extension project. You also need to set debugging properties so that a new instance of the IDE is started. First you'll set those debugging properties.

1. Right-click the FrameViewHello project folder, then click Properties.
2. In the Project Properties dialog, on the Debugger panel, enter values as described at Setting Up Extension Debugging Properties.

Next, you'll create a build.xml file.

1. Right-click the FrameViewHello project folder, then click Properties.
2. In the Project Properties dialog, on the Build panel, click Export to Ant file, then click Cancel.
3. In the Application window, locate the exported_build.xml file generated for you.
4. Rename exported_build.xml to simply build.xml, then double-click the file to open it in Source View.
5. In the build.xml file, scroll down to the "build" target, the add the following as the last task in the target:

    <zip destfile="${platformhome.local.directory}/workshop/extensions/${output.filename}"
            basedir="${dest.path}"
            includes="**/*.*"
            encoding="UTF8"> <!-- jar filenames are UTF8-encoded -->
            <zipfileset dir="${project.local.directory}"
            excludes="build.xml,**/CVS/**,**/*.java,${output.filename}"
            includes="**/*.*"/>
    </zip>

This zip task zips your extension output and copies it to the WORKSHOP_HOME/extensions folder, where WebLogic Workshop can find it when the IDE starts.

6. Save and close the file.
7. Right-click the FrameViewHello project folder, then click Properties.
8. In the Project Properties dialog, on the Build panel, click Use Ant build. By default, the build target should be displayed as "build", and that's as it should be.
9. Click OK.

Now you're set up to build and debug an extension project. Next you'll create the source files that make up your extension.

To Create an extension.xml File

An extension.xml file connects your extension code with the IDE. You'll create an extension.xml file to tell the IDE a few simple things about your frame view, such as how the view should be listed on a menu command. But your extension.xml will also point the IDE to the Java code that it should execute for your extension's logic and user interface. You'll write that code in a moment.

1. Right-click the FrameViewHello/META-INF folder, the click New -> Other File Types.
2. In the New File dialog, on the left click All, on the right click XML File.
3. In the File Name box, type extension.xml.
4. Click Create.
5. Replace the file contents generated for you with the following:

       <extension-definition>
           <extension-xml id="urn:com-bea-ide:frame">
               <frame-view-set>
                   <frame-view id="sayhello" class="myframeview.HelloWorldFrame"
                       label="Say Hello" />
               </frame-view-set>
               <application-layout id="main">
                   <frame-layout id="main">
                       <frame-container orientation="east" proportion="20%">
                           <frame-container orientation="tabbed">
                               <frame-view-ref class="myframeview.HelloWorldFrame" />
                           </frame-container>
                       </frame-container>
                   </frame-layout>
               </application-layout>
           </extension-xml>

       </extension-definition

   The <extension-definition> element is always the root of an extension.xml file. A file can define many extensions, each specified by a separate <extension-xml> stanza. Here, the definition contains two main chunks of information. The <frame-view-set> stanza simply tells the IDE that this frame view exists, what's its menu and tab label should be, what class to use, and so on. The <application-layout> stanza tells the IDE where to display the frame view on startup. Of course, if you (or your extension's user) has been using the IDE, then preferences for the position of frames has already been stored locally. In that case, this frame will need to be selected from the View menu.

6. Save and close the file.

Now it's time to write the Java code.

To Write the Extension's Java Code

Your extension's user interface and logic are defined in Java classes. In the extension.xml snippet you created, you specified the class myframeview.HelloWorldFrame, so that's the class you're going to create here.

A frame view class implements the IFrameView interface, which provides a method the IDE can use to get your frame UI. It also provides a method the IDE can use to ask whether your frame should be available for display. Start by creating a new package folder and Java class.

1. Right-click the FrameViewHello/src folder you created earlier, then click New -> Folder.
2. In the New Folder dialog, type myframeview for the folder name, then click OK.
3. Right-click the new myframeview folder, then click New -> Java Class.
4. In the New File dialog, on the left click Common, on the right click Java Class.
5. In the File Name box, type HelloWorldFrame.java, then click Create.
6. In the JAVA file that's created, paste the following code:

       package myframeview;

       import com.bea.ide.ui.frame.IFrameView;
       import com.bea.ide.util.swing.DialogUtil;
       import java.awt.Component;
       import javax.swing.JPanel;

       public class HelloWorldFrame
           extends JPanel implements IFrameView
       {
           private javax.swing.JButton btnSayHello;
           /**
            * Construct this frame by calling the method that assembles its UI.
            */
           public HelloWorldFrame()
           {
               initComponents();
           }

           /**
            * The IDE calls this to get the UI.
            */
           public Component getView(String id)
           {
               return this;
           }

           /**
            * The IDE calls this to find out if it should make this
            * frame's UI available for display.
            */
           public boolean isAvailable()
           {
               return true;
           }

           // Put together the user interface.
           private void initComponents()
           {
               // A simple button whose label is "Say Hello"
               btnSayHello = new javax.swing.JButton();
               btnSayHello.setText("Say Hello");
               // Connect event handling by adding an action listener.
               btnSayHello.addActionListener(new java.awt.event.ActionListener()
               {
                   // If something happens, show a dialog with a friendly message.
                   public void actionPerformed(java.awt.event.ActionEvent event)
                   {
                       DialogUtil.showInfoDialog(null, "Hello World!");
                   }
               });
               // Add the new button to this panel.
               add(btnSayHello);
           }
       }

That's it. Now to try it out. If you got set up for debugging as described earlier in this topic, you should be able to click the Start button to run the project. When the new IDE instance has started, if the Say Hello frame isn't visible, you can select it from the View -> Windows menu. Click the Say Hello button, and you should see the friendly dialog. With the frame docked, it might look something like this:

When you've tried out the extension, close the second IDE instance (you can also switch to the first instance and click the Stop button). If you want to try out debugging, set a breakpoint at the first line of the initComponents method, then run the extension again.

## Where to Go From Here

The extension you built with this tutorial is one of several types you can build — and it's one of the simplest. In addition, the extension API includes support for a great deal of functionality that can be used within multiple extension types.

For more information on setting up for building and debugging an extension, see Debugging Extensions. For more on frame view extensions, see Adding Dockable Frames.

Related Topics

Extending the WebLogic Workshop IDE