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

7

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:

&lt;bp:rating id=&quot;rating&quot; maxGrade=&quot;5&quot; includeNotInterested=&quot;true&quot; includeClear=&quot;true&quot; <br />   hoverTexts=&quot;#{RatingBean.ratingText}&quot; notInterestedHoverText=&quot;Not Interested&quot; <br />   clearHoverText=&quot;Clear Rating&quot; grade=&quot;#{RatingBean.grade}&quot;/&gt;<br />

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() {<br />    return new String[]{&quot;Hate It&quot;, &quot;Below Average&quot;, &quot;Average&quot;<br />                       , &quot;Above Average&quot;, &quot;Love It&quot;};<br />}<br />

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.

&lt;bp:autoComplete size=&quot;20&quot; maxlength=&quot;100&quot; id=&quot;boyField&quot;<br />                           completionMethod=&quot;#{BoysBean.completeBoysName}&quot;<br />                           value=&quot;#{BoysBean.name}&quot; required=&quot;true&quot;/&gt;<br /><br />

The BoysBean class is this one:

package nl.amis.jsf;<br />import com.sun.j2ee.blueprints.ui.autocomplete.AutoCompleteUtilities;<br />import com.sun.j2ee.blueprints.ui.autocomplete.CompletionResult;<br />import java.util.Arrays;<br />import javax.faces.context.FacesContext;<br /><br />public class BoysBean {<br />    private String name;<br />    public BoysBean() {<br />    }<br />    public void completeBoysName(FacesContext context, String prefix, <br />                                 CompletionResult result) {<br />        String[] names = <br />            new String[] { &quot;Jack&quot;, &quot;James&quot;, &quot;Igor&quot;, &quot;John&quot;, &quot;Jim&quot;, &quot;Indiana&quot;, <br />                           &quot;Irvin&quot;, &quot;Leo&quot;, &quot;Lenny&quot;, &quot;Leonard&quot;, &quot;Lou&quot;, &quot;Lubby&quot;, <br />                           &quot;Matt&quot;, &quot;Matthew&quot;, &quot;Milton&quot; };<br />        Arrays.sort(names);<br />        AutoCompleteUtilities.addMatchingItems(names, prefix, result);<br />    }<br />    public void setName(String name) {<br />        this.name = name;<br />    }<br />    public String getName() {<br />        return name;<br />    }<br />}<br /><br />

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

Share.

About Author

Lucas Jellema, active in IT (and with Oracle) since 1994. Oracle ACE Director for Fusion Middleware. Consultant, trainer and instructor on diverse areas including Oracle Database (SQL & PLSQL), Service Oriented Architecture, BPM, ADF, Java in various shapes and forms and many other things. Author of the Oracle Press book: Oracle SOA Suite 11g Handbook. Frequent presenter on conferences such as JavaOne, Oracle OpenWorld, ODTUG Kaleidoscope, Devoxx and OBUG. Presenter for Oracle University Celebrity specials.

7 Comments

  1. Kedar Mhatre on

    Lucas, bpcatalog-ee5-ea-0.8-installer.jar is for Java EE 5 and JSF 2.1 compliant. Lib folder contains bp-ui-14.jar which for older version. When I use these jars in JDeveloper 11g (ADF BC RC) it fails with Illegal state exception.
    Have you worked with this application on 11g?

  2. hi,
    In my application,I want a pop-up calendar.
    For that I downloaded AJAX JSF Components – along with the entire Blueprints Catalog.
    I placed these under WEB-INF/lib folder of my project.
    and I rebuild the project.But I am getting the error like

    Error(342): Unable to instantiate tag: ui:popupCalendar (class: com.sun.j2ee.blueprints.ui.popupcalendar.PopupCalendarTag) Make sure that the tag class is available and that the tag library containing the class is not excluded from this application.
    Error(342): Unable to find class for bean: null defined by tag with class: com.sun.j2ee.blueprints.ui.popupcalendar.PopupCalendarTag

    but the bp-ui-14.jar(for the class PopupCalendarTag.class) is there under WEB-INF/lib folder.
    what is the solution to my problem.
    Can anyone pls suggest me the solution

  3. Yeah, after looking into it a bit more, I also narrowed it down to the render kit. It seems that once you place a component that requires the render kit (ie, just about anything), your BluePrint (or other library) ceases to function. Looking at the rendered HTML, I can see that the scripts that BluePrint relies on are no longer included, so someone must be overriding their inclusion (for whatever reason). Disappointing is, I think, a very mild way of putting it. Standardization really needs to be worked out to avoid this type of frustration. Thanks for your reply and information!

  4. K: you most certainly have a point. I have recently done a lot of investigation into various JSF implementations and I was very disappointed at the lack of interoperability. Very few implementations can actually work together. For example ICEFaces, Backbase, ADF Faces and Trinidad are all mutually exclusive. MyFaces Tomahawk on the other hand can be used in conjunction with many other implementations, at least ADF Faces and Trinidad. I had no luck so far mixing ADF Faces with the SUN Java BluePrint JSF Components – so that is not good news – although I am not ready to give up yet. I have not done an extensive analysis of the issues. Using Project Woodstock together with ADF Faces also seems to be a problem. I have not yet tried the JBoss Rich Ajax components. I did try RichFaces, without success. I cannot say for sure where the issues stem from. One issue is that some JSF implementations require their very own render kit and these requirements clash.

  5. Very handy….except…

    If you try using these components on a page with an “af:panelPage,” they stop working. I’m fairly new to ADF, so I wouldn’t be surprised if there’s a good reason for this, but, since I know of no such “good reason,” I have to say: unless there’s a way to work around this, the functionality of these components seems rather limited.

    If I’m wrong, then, please, correct me. I’d love to make use of this functionality, but would also like the layout ease provided by “panelPage.”