Using the Sun Java BluePrints AJAX JSF Components in your own JSF Web Application

One of quite a few open source JSF libraries available to JSF Web Application developers is the Sun Java Blueprints AJAX JSF Components. This set of AJAX-powererd JSF components can be found at: https://blueprints.dev.java.net/ajaxcomponents.html. The collection contains several interesting, useful components, such as Auto Complete Text Field ("Google Suggest"), Progress Bar, Popup Calendar, Rich Text Editor, Google Map Viewer, Rating and several more. A second set requires a JEE5 Application Server, such as Glassfish, and contains Popup Balloon, Ajax Validator, RSS Reader and more.

In this article I will demonstrate how you can use these Sun Java Blueprints AJAX JSF Components in your own JSF Web applications, to complement whichever is your primary JSF implementation, for example Sun RI, Apache MyFaces Tomahawk or Trinidad or Oracle ADF Faces. I will make use of Oracle JDeveloper as IDE, but the steps are similar in other IDEs.

The steps in short:

• Download the AJAX JSF Components – along with the entire Blueprints Catalog
• Copy the AJAX JSF Components to the WEB-INF\lib directory of your JSF project
• Create Project Libraries for the JARs copied from the Blueprints Catalog as well as a Project Tag Library for the BluePrintsAJAXJSFTags
• Add the taglib’s namespace to the jsp:root element in the JSF page
• Drag & Drop the desired components to the JSF page and provide the necessary configuration
• Run the application

Note: the Blueprints AJAX JSF components can be freely mixed with JSF components from other libraries and implementations. That is: some JSF libraries mix more easily than others. In a later post I will dwell a little on the interoperability issues I have run into with ADF Faces, MyFaces Trinidad and ICEFaces.

Download the AJAX JSF Components – along with the entire Blueprints Catalog

Download and run bpcatalog-ee5-ea-0.8-installer.jar from https://blueprints.dev.java.net/servlets/ProjectDocumentList?folderID=4144&expandFolder=4144&folderID=0. This will create a directory structure which contains the BluePrints Catalog. Note: the apps\webtier directory contains a number of example projects that we can use for inspiration on how to use the AJAX JSF Components.

Create the JSF Web Application in JDeveloper

If you have not already an existing JSF Application that you want to use the Blueprints AJAX JSF Components for, now is a good moment to create one. Start JDeveloper 10.1.3.x. From the New Gallery, pick Application. Do not select a technology template.
 
Create an new JSF page. This creates the WEB-INF\lib directory in your project.

Copy the AJAX JSF Components to the WEB-INF\lib directory of your JSF project

In order to use the AJAX JSF Components, all libraries that contribute to their run time functionality need to be copied to our own JSF application’s WEB-INF\lib directory.

 
Create Project Libraries for the JARs copied from the Blueprints Catalog as well as a Project Tag Library for the BluePrintsAJAXJSFTags
Go to Edit Project Properties. Select the Libraries Node. Press the Add Jar/Directory button. Select all JARs in the WEB-INF\lib directory of the project.  Press Select. Now select the JSP Tag Libraries Node. Click on Add. Select the User Node and click New. Select the bp-ui-14.jar file in the WEB-INF\lib directory. Press Open, Press OK.
 
Click OK to return from the Project Properties Editor.

 
The Component Palette should now contain the BluePrintsAjaxJSFTags. These are the components we can choose from in the EA-0.8 relase of the JEE5 BluePrints Catalog.

Drag & Drop the desired components to the JSF page and provide the necessary configuration

Dragging a BluePrint AJAX JSF Component to your JSF page should add the taglib’s namespace (xmlns:bp="http://java.sun.com/blueprints/ui/14") to the jsp:root element in the JSF page.

The easiest component to use is probably the Popup Calendar. Simply drag & drop it to the JSF page. Run the page. It gives us a popup calendar to choose a date value. It can be configured with a Date Format Pattern and a Locale String. The Locale determines the names of Week Days and Months displayed in the Popup Calendar:

 
The page looks like this:
 
When we click the Calendar Icon, the Calendar appears. Note: it pops up in-line, using a DIV. It does not require a Popup Window (that may be blocked by popup blockers).

 
Of course we can use CSS styles to make it appear a little prettier. More details on using this component can be found here: https://blueprints.dev.java.net/complib/v2/popup-calendar.html .

Introducing the Rating Component

A nice little component in the BluePrints AJAX JSF Components set is the Rating Component. It allows the user to specify a rating, for any element that we want the user to assign a rating to. The rating is visualized with stars, in a way that is reminiscent of Amazon’s Book Ratings.
Again, using the component takes nothing more than dragging it to our page. It can be configured in several ways; see https://blueprints.dev.java.net/complib/v2/ratings.html  for details. SImply put: this component can be used to display and edit an integer value through a number of stars. The maximum number of stars can be configured.

For example:

<bp:rating id="rating" maxGrade="5" includeNotInterested="true" includeClear="true" 
   hoverTexts="#{RatingBean.ratingText}" notInterestedHoverText="Not Interested" 
   clearHoverText="Clear Rating" grade="#{RatingBean.grade}"/>

Note: the number of stars is set through maxGrade.

 
The RatingBean has been set up in the faces-config.xml file and contains the getRatingText() method:

public String[] getRatingText() {
    return new String[]{"Hate It", "Below Average", "Average"
                       , "Above Average", "Love It"};
}

Meeting the Auto Complete Text Field Component

The archetype AJAX component is of course Google Suggest, the list of suggestions that is displayed as soon as a user starts typing a value into a text field and that is updated as the user keeps typing and that allows selection of a value. This type of functionality uses AJAX to send the strings entered by the user to the server and receive from the server a small list of suggested values that match the string entered so far.

The Google Suggest or more generically called Auto Complete functionality is very useful in situations where the list of possible values is much too large for displaying in a dropdown list and use of a (popup) List of Values is not desirable. See for details on how to configure this component: https://blueprints.dev.java.net/complib/v2/auto-complete.html .

We will create a simple example of the Auto Complete Text Field Component in the BluePrints AJAX JSF Collection, one that is used for selecting a boy’s name.

<bp:autoComplete size="20" maxlength="100" id="boyField"
                           completionMethod="#{BoysBean.completeBoysName}"
                           value="#{BoysBean.name}" required="true"/>

The BoysBean class is this one:

package nl.amis.jsf;
import com.sun.j2ee.blueprints.ui.autocomplete.AutoCompleteUtilities;
import com.sun.j2ee.blueprints.ui.autocomplete.CompletionResult;
import java.util.Arrays;
import javax.faces.context.FacesContext;

public class BoysBean {
    private String name;
    public BoysBean() {
    }
    public void completeBoysName(FacesContext context, String prefix, 
                                 CompletionResult result) {
        String[] names = 
            new String[] { "Jack", "James", "Igor", "John", "Jim", "Indiana", 
                           "Irvin", "Leo", "Lenny", "Leonard", "Lou", "Lubby", 
                           "Matt", "Matthew", "Milton" };
        Arrays.sort(names);
        AutoCompleteUtilities.addMatchingItems(names, prefix, result);
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getName() {
        return name;
    }
}

When we run the page, we see:

 
Entering additional characters will cause the list of suggested names to refresh. Clicking the name we desire will make the list of suggestions disappear.
 

Other Components

Othe
r interesting compone
nts in the BluePrints AJAX JSF Components Library include the Google MapViewer (https://blueprints.dev.java.net/complib/v2/map-viewer.html and also: http://brainoff.com/gmaps/mgeocoder.html#) and the RichTextArea (Editor, http://javanet1-ws.locaweb.com:8080/bpcatalog/docs/taglib-docs/bp-ui-14/bp/richTextarea.html ) as well as the ProgressBar (https://blueprints.dev.java.net/complib/v2/progress-bar.html). More on these in a later article.

Resources

Download JDeveloper 10.1.3.2 Application using Sun Java BluePrint AJAX JSF components