Edgar Silva's Blog

Creating a new Components Palette for Java Server Faces Dev in NetBeans 5.5

Motivation

If you want to create an application using Java Server Faces using NetBeans you have really useful features as which turn this task simple. Nevertheless we have a lot of open-source projects that can help us on JSF Developement, such as: MyFaces, Facelets , IceFaces , Ajax4JSF and others. I am sure, that some of the developers envolved with these projects would like to make the development easier using their components. If you need a complete solution to make your components availabe in NetBeans, this post can to give out some tips and tricks in how to do that.

NetBeans Benefits for JSF Components Creators

NetBeans, since of its default installation, counts with a lot of nice features, as the following:

• JSP and JSPX Syntax Highlight
• HTML and XHTML Syntax Highlight
• XML Syntax Highlight
• Code Completion for JSP, XML and HTML
• An embedded TomCat to test and debug
• Web Project Types and features for JSF and Struts
• Component Palette Items for HTML and JSP

If NetBeans did these things for us, why is not possible to add our own components on JSP/JSF Component Palette?I am sure you can think: "This sound quite hard...", However I can say: Don't worry! Read this post and I am sure you will have a different spot.

Creating a New Module Suite Project

A Module Suite is necessay to create a set of new Modules, our Components Items are one Project Module inside a Module Suite. Besides palette components, we could to add new modules to suite, in addition to this, when you create a suite you can run another NetBean´s instance, and then dubug and test our modules can be easier. To create a new Module Suite, click on File/New/Project, and then select NetBeans Plugin-Modules category and click on the Module Suite Project., as it is shown in the following image:

Click on Next button, and fill the suite's data with the following information:

• Project Name: faces-pro
• Project Location: This you can to choose anything you want

Creating a New Module Project

A Module Project is your set of plugin(s), we often use a Module to add one or more plugins in NetBeans. As well as you can use one Project Module per new Plugin you are creating. To create a new one, click on File/New/Project menu and select NetBeans Plugin-Modules category and click on the Module Project..After click on Next button, you will see the Project settings informations, basically we have to give a name to project and select which Suite this module will be inserted on, as it is shown in the following image:

After to click on Next button, you will see some informations about your Module Project, look the following list:

• Code Base Name: The standard package for your classes and files
• Module Display Name: Some impressive display name, for example: Java Server Faces Pro Tags
• Code Base Name: The standard package for your classes and files
• Localizing Bundle: NetBeans really cares to I18N so everything you did in your plugins always you will have a file to put your messages, informations and etc
• XML Layer: This is in my opinion the most important file when you are doing NetBean's plugins, just because almost everything you expose to NetBeans platform enviorement is declared on this file, such as our new Palette Items.

Creating a JSP Palette Component Item: SelectOneMenu

The SelectOneMenu is responsible in generating an html select with some dinamic data. Then, We will create a class to represent this code generation inside of JSP file. The class will be called SelectOne.java .
The following code shows you how you can handle the drag and drop from palette to source editor in NetBeans:

import java.awt.Dialog;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import javax.swing.text.BadLocationException;
import javax.swing.text.JTextComponent;
import org.openide.DialogDescriptor;
import org.openide.DialogDisplayer;
import org.openide.text.ActiveEditorDrop;

public class SelectOne implements  ActiveEditorDrop {
    
    final protected SelectOnePanel tag = new SelectOnePanel();
    
    private String id;
    
    private String value;
    
    private String tagValue;
    
    /** Creates a new instance of SelectOne */
    public SelectOne() {
    }
    
    private String createBody() {
        getPropsForTag();
        String SelectOne;
        SelectOne = getTagValue();
        return SelectOne;
    }
    
    public boolean handleTransfer(JTextComponent targetComponent) {
        String body = createBody();
        try {
            FacesPaletteUtilities.insert(body, targetComponent);
        } catch (BadLocationException ble) {
            return false;
        }
        return true;
    }
    
    
    protected void getPropsForTag() {
        DialogDescriptor tagdialogdescriptor = 
new DialogDescriptor(tag,"Java Server Faces Pro");
        tagdialogdescriptor.setModal(true);
        tagdialogdescriptor.setLeaf(true);
        tagdialogdescriptor.setOptionType(DialogDescriptor.OK_CANCEL_OPTION);
        
        Object ret =  DialogDisplayer.getDefault().notify(tagdialogdescriptor);
        
        if (ret == DialogDescriptor.OK_OPTION) {
          StringBuffer buffer = new StringBuffer();
          buffer.append(String.format("", tag.id.getText(), tag.value.getText()));
          buffer.append("\n  ");
          buffer.append("\n");
          
          setTagValue(buffer.toString());
        } else {
          setTagValue("");
        }

As you can see our SelectMenu class, implements the org.openide.text.ActiveEditorDrop, as which allow us to drag an item from palette and drop on source code, basically the executed method to automate this task is called: handleTransfer(). Look that in the method calling we have other two pieces: createBody() and FacesPaletteUtilities.insert(body, targetComponent). We will describe these methods in the following list:

• createBody() : This method calls a Dialog to interact with user before insert the code. This dialog basically ask you about the values that we can fill in the SelecOneMenu tag (id and value).
• FacesPaletteUtilities.insert(): This static method is a helper to handle the text insertion on the source code.

Using Dialogs to Interact with Users

Certainly you are really proud with yourself, cause you are improving a lot the NetBeans IDE with your own component´s palette, and then you will give out a real gift to community that want use your group of components or even your internal development team. That´s you can give a professional impression about your pallete, to make it real we create a simple JPanel, and the most important items on this JPanel are 2 JTextFields, called id and value, respectivelly . They have to declared as public

    protected void getPropsForTag() {
        DialogDescriptor tagdialogdescriptor = new DialogDescriptor(tag,"Java Server Faces Pro");
        tagdialogdescriptor.setModal(true);
        tagdialogdescriptor.setLeaf(true);
        tagdialogdescriptor.setOptionType(DialogDescriptor.OK_CANCEL_OPTION);
        
        Object ret =  DialogDisplayer.getDefault().notify(tagdialogdescriptor);
        
        if (ret == DialogDescriptor.OK_OPTION) {
          StringBuffer buffer = new StringBuffer();
          buffer.append(String.format("", tag.id.getText(), tag.value.getText()));
          buffer.append("\n  ");
          buffer.append("\n");
          
          setTagValue(buffer.toString());
        } else {
          setTagValue("");
        }
    }

Creating a Insertion code Helper: FacesPaletteUtilities

This class acts as a helper when we want to add some text in a existing source opened in the our JSP Editor. Look its source code in the following code listing:

import javax.swing.text.BadLocationException;
import javax.swing.text.Caret;
import javax.swing.text.Document;
import javax.swing.text.JTextComponent;
import org.netbeans.editor.BaseDocument;
import org.netbeans.editor.Formatter;

public class FacesPaletteUtilities {
    public static void insert(String s, JTextComponent target)
    throws BadLocationException {
        insert(s, target, true);
    }
    
    public static void insert(String s, JTextComponent target, boolean reformat)
    throws BadLocationException {
        
        if (s == null)
            s = "";
        
        Document doc = target.getDocument();
        if (doc == null)
            return;
        
        if (doc instanceof BaseDocument)
            ((BaseDocument)doc).atomicLock();
        
        int start = insert(s, target, doc);
        
        if (reformat && start >= 0 && doc instanceof BaseDocument) {  
            int end = start + s.length();
            Formatter f = ((BaseDocument)doc).getFormatter();
            f.reformat((BaseDocument)doc, start, end);
        }
        
        if (doc instanceof BaseDocument)
            ((BaseDocument)doc).atomicUnlock();
        
    }
    
    private static int insert(String s, JTextComponent target, Document doc)
    throws BadLocationException {
        
        int start = -1;
        try {
            //at first, find selected text range
            Caret caret = target.getCaret();
            int p0 = Math.min(caret.getDot(), caret.getMark());
            int p1 = Math.max(caret.getDot(), caret.getMark());
            doc.remove(p0, p1 - p0);
            
            //replace selected text by the inserted one
            start = caret.getDot();
            doc.insertString(start, s, null);
        } catch (BadLocationException ble) {}
        
        return start;
    }
}

Declaring Additional informations and Resources

Now it´s time to create a component descriptor file, which is a XML file. This file describes informations about our component, you will this file on the same package of SelectMenu class. The file name will be SelectOne.xml, and its content is the following:

As you can see we had been definied the: Class component item, its icon representation for both sizes (16X16 and 32X32). Moreover we definied the keys for name and description of our component item.

Declaring our Component in layer.xml

This one of the most important steps on this post, we will declare our component inside Netbeans enviroment. Look this file in the following image:

Well, that´s all you need to create a new item on JSF Palette. Now you can Run your Module Suite.

Some Details about Modules Development

Libraries Dependencies

When you are creating a NetBean´s Module , depending of the kind of things you are creating, some dependencies should be mandatories. To add these dependencies, click with left button over your Module Project and click on Properties option, take a look on Libraries Item on left list, on this panel you can add your module´s dependencies.
To this module we did, you will need the modules shown on the following image:

Icons for your Components

The years I spent on University was not enough to learn how to create cool and beautiful icons, In addition, I am not an artist as my famous friend: Tim Boudreau , that created a lot of NetBeans's icons.
Then if you want your users really excited with, is had better you have some friends in our team that don't create your icons. =)

Showing our plugin In Action

Now it's time to see our plugin running:
Look our new Component Item and new Palette:

Dragging our component to Source Editor:

The Code was inserted on the JSP source code editor:

I hope this post could be useful for frameworks developers, or even developers at companies using NetBeans and want to create or add your own component items to turn JSP and JSF delopment easier and faster.

If you want the project´s files, please send me an e-mail: edgar (em) edgarsilva.com.br

Comments

• This is great.

  As an alternative to adding new palette items, is it possible to customize some of the templates that NetBeans uses to generate JSF pages.

  I use facelets, for instance. I would really like to convert the Entity Class pages (Detail, List, Edit and New) to use facelet tags instead of regular JSF tags. I'd also like to change the files from JSPs to xhtml files, but that is less important.

  Changing templates would be easier for me to do than module development (even with your excellent instructions).
  

  Posted by: siderean on January 11, 2007 at 12:22 PM

This work is licensed under a Creative Commons License.