X Tutup
The Wayback Machine - https://web.archive.org/web/20070813084746/https://ajax.dev.java.net/usingFaces.html
Login | Register
My pages Projects Communities java.net

Using jMaki Widgets as JavaServer Faces Components


Alpha Version

A jMaki widget is an AJAX-enabled widget that is wrapped as either a JSP custom tag handler or a JavaServer Faces component.  A typical jMaki widget consists of three resources:

  • component.htm: an HTML template for rendering the widget to the page
  • component.js: a JavaScript file that "bootstraps" the widget for use as a JSP tag handler or JavaServer Faces component
  • component.css: a stylesheet that defines styles for the widget
A more complicated widget might require additional resources.

Behind the scenes, jMaki wraps the widget's resources into a JSP custom tag handler or JavaServer Faces component.  Using the custom jMaki tag libraries, you can add a jMaki widget to your page without having to deal directly with the widget resource files.

This tutorial shows you how to use a jMaki widget as a JavaServer Faces component in your application. Please see Using jMaki Widgets for more in-depth information on what a jMaki widget is and how it works.   If you don't already know to use a jMaki widget as a JSP tag handler, please see  Getting Started Using jMaki Widgets as JSP Tag Handlers.

Contents

Checklist
Setting Up
Adding Required Servlet Mappings
Adding Widget Resources
Adding the Widget to Your Page
Loading Your Own Data into the Widget
Accessing the Widget's Value

Checklist

To get yourself set up to use this tutorial, make sure that you have the following:

  • The Java SE SDK, version 5 or or later.
  • GlassFish or the Java EE SDK, version 1.4 or later. 
  • The jMaki distribution zip file.
  • The jMaki samples zip file.
  • The usingFaces.zip file, unpacked. The usingFaces directory includes the blankFacesApp and solutionFacesApp subdirectories.  You'll use the blankFacesApp directory to build the sample application.  The solutionFacesApp directory contains the solution to the application that you'll build.
  • A browser that supports JavaScript.

Setting Up

Before starting the exercises, set up your environment first by performing the following steps.
  1. Add the paths to your Java SE 5 and Java EE SDK installations to your system path.
  2. Add the path to the Ant build tool, included with GlassFish and the Java EE SDK, to your system path.
  3. Unpack the jMaki distribution file.
  4. Wherever you like, unpack the jmaki.war file that was included in the zip file that you unpacked in the previous step:
    jar xvf jmaki.war
  5. Unpack usingFaces.zip.
  6. Open the build.properties files in the blankFacesApp and solutionFacesApp directories in an editor and do the following
    1. Set the javaee.home property to the path to your Java EE installation.
    2. Set the javaee.server.passwordfile property to a file that contains the password for your application server.
Hereafter, this tutorial uses the following path variables:
  • JavaEE_HOME: The path to your Java EE or GlassFish installation
  • jMaki_INSTALL: The path to where you unzipped the jMaki distribution file
  • samples_INSTALL: The path where you unzipped the jMaki samples file.
  • tutorial_INSTALL: The path to where you unzipped the usingFaces.zip file


Adding Required Servlet Mappings

All requests for a page containing JavaServer Faces components must go through FacesServlet.  Therefore, you need to provide mappings to FacesServlet in your application's deployment descriptor if you are using jMaki widgets as JavaServer Faces components.

To add the required servlet mapping, follow these steps:

  1. Open the web.xml file located in the <tutorial_INSTALL>/blankFacesApp/web/WEB-INF directory in an editor.
  2. Add the following mappings to the FacesServlet:
    <servlet>
       <servlet-name>Faces Servlet</servlet-name>
       <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
       <load-on-startup> 1 </load-on-startup>
    </servlet>
    <servlet-mapping>
       <servlet-name>Faces Servlet</servlet-name>
       <url-pattern>/faces/*</url-pattern>
       </servlet-mapping><servlet-mapping>
       <servlet-name>Faces Servlet</servlet-name>
       <url-pattern>*.faces</url-pattern>
    </servlet-mapping>
  3. Save the file.

Adding Resources Required by the Widget

All applications that use jMaki widgets need to include the following files:
  • The jmaki.js file, which contains the JavaScript bootstrapper and utilities that manage the loading of jMaki widgets
  • The ajax-wrapper-comp-0.9.7.jar file, which contains the code used to wrap widgets as JSP tag handlers or JavaServer Faces components.
In addition to these resources, applications using the Dojo combobox widget need to include the widget's component.htm and component.js files and the Dojo scripts that implement the Dojo combobox widget. 

To add these resources, do the following:
  1. Copy jmaki.js from <jMaki_INSTALL>/jmaki-core/web/resources to <tutorial_INSTALL>/blankFacesApp/lib. 
  2. Copy ajax-wrapper-comp-0.9.7.jar from <jMaki_INSTALL>/jmaki-core/web/WEB-INF/lib to <tutorial_INSTALL>/blankFacesApp/lib.
  3. Copy the combobox directory, located in <samples_INSTALL>/resources/dojo, and all of it's contents to the <tutorial_INSTALL>/blankFacesApp/src/resources/dojo directory.  The combobox directory contains the widget's component.js and component.htm files.
  4. Copy the <samples_INSTALL>/resources/libs/dojo directory to the <tutorial_INSTALL>/blankFacesApp/web/resources/libs directory.  This set of resources contains all the script that implements the Dojo combobox widget as well as all the other Dojo widgets.
The following figure shows where all of the required resource files are located in the built application WAR file.

Location of required resource files in the application WAR file

Besides these resource files, the blankFacesApp directory also contains all the files that a standard JSP application needs.  While going through this guide, you'll add the pieces that are essential to getting the combobox widget to work in your application.


Adding the Widget as a JavaServer Faces Component

Now that you have set up your application and added the widget's resources to it, you can add the jMaki widget to your page.  You do this by using the ajax custom tag and specifying some properties on the tag to identify which widget you are adding to the page. 

You can use the jMaki widget as a JSP custom tag or as a JavaServer Faces component.   The jMaki project provides two TLDs: one of them defines the ajax tag as a custom JSP tag; the other defines the ajax tag as a custom JavaServer Faces component tag.  Which TLD you declare in your page determines whether the widget is wrapped as a JSP custom tag handler or a JavaServer Faces component.

In this exercise, you'll add the combobox widget to the page as a JavaServer Faces component and run the application to test it out.

Using the ajax Custom Tag to Add the Widget to the Page


 To add the Dojo combobox widget as a JavaServer Faces component, do the following:

  1. Open the comboboxFaces.jsp page, located in the <tutorial_INSTALL>/blankFacesApp/web directory in an editor.
  2. Add the following tag library declaration to the top of the page:
    <%@ taglib prefix="a" uri="http://java.sun.com/jmaki-jsf" %>
    This tag library defines the custom ajax tag that represents a JavaServer Faces component.

  3. In between the beginning and ending form tag on the comboboxFaces.jsp page, add the following ajax tag:
    <a:ajax id="cb1" name="dojo.combobox" />

  4. Save the file.
The ajax tag you added in step 3 uses two attributes: the id attribute and the name attribute.

The id attribute identifies the widget so that you can refer to it from other components in the page.

The name attribute identifies the jMaki widget as dojo.combobox.  In this case, jMaki searches the resources directory of your application and finds the dojo directory and then the combobox directory, which contains the widget's resource files. 

The ajax tag can take other attributes.  See Using jMaki Widgets for the complete list of attributes.  Keep in mind that the attributes you will need to use differ for each widget.  The best way to learn how to use a particular widget is to look at the example JSP pages and the widget.json files, located in each widget's directory of the samples distrbution file that you downloaded.

Running the Application

Now you're ready to run your application:
  1. Open a terminal window and go to the <tutorial_INSTALL>/blankFacesApp directory.
  2. Run the following command:
    ant
  3. Launch your application server.
  4. Go to the <tutorial_INSTALL>/blankFacesApp/dist directory.  You should see the blankFacesApp.war file there.
  5. Deploy the war file:
    asadmin deploy blankFacesApp.war
  6. Launch your browser and enter the following URL:
    http://localhost:8080/blankFacesApp
  7. Select JavaServer Faces component combobox widget.

You should see the combobox widget, but it won't have any data in it.  The next section explains how to import your own data into the widget.

Loading Your Own Data into the Widget

Using jMaki Widgets showed how to load your own data from a JavaScript file into a widget.  In this exercise, you'll see how to load data from a JavaServer Faces managed bean.

A couple of the features that JavaServer Faces technology offers is its flexible, extensible component model and its managed bean facility.  With the component model and managed bean facility, you can bind UI components to server-side data, wire component-generated events to server-side code, and save and restore component state.

The jMaki project allows you to use a JavaServer Faces managed bean to populate the data of a widget wrapped as a JavaServer Faces component, much the same way as you would populate data in any other JavaServer Faces component.  In this exercise, you'll load data from a managed bean by performing these steps:
  • Defining variables to hold the data set
  • Creating a value-binding to a managed bean property
  • Defining a method that converts the list of countries to JSON
  • Configuring the managed bean
  • Pointing the ajax tag's value attribute to a property on the managed bean
The <tutorial_INSTALL>/blankFacesApp/java/src/com/sun/facesApp/dojo directory already contains a skeleton managed bean Java source file, called ComboBoxBean.java.  You'll use this file throughout this exercise.

Defining Variables to Hold the Data Set

 
Now, you'll need to create two arrays: one that holds the names of the countries and another that holds the corresponding country codes.

  1. Open ComboBoxBean.java, located in <tutorial_INSTALL>/blankFacesApp/java/src/com/sun/facesApp/dojo, in an editor.
  2. In ComboBoxBean.java, add a private array called countries and set it to the list of countries shown in the following code:
    private String[] countries =new String[] {
    	"Canada", "France", "Uganda", "Ukraine", "United States of America",
    	"United Kingdom","Japan", "Korea", "Jamaica", "Thailand"
    };
  3. Add a private array called countryCodes and set it to the country codes that match the country names stored in the countries array:
    private String[] countryCodes =
    	new String[] {"CA", "FR", "UG", "UR", "USA", "UK", "JP", 
    		"KR", "JA", "TH"};
  4. Save the file.

Creating a Value-Binding to a Managed Bean Property

In a JavaServer Faces application, a JSP page can get and set a component value bound to a managed bean property by referencing the property from the component tag's value attribute.  The jMaki project allows you to get a value from a managed bean using a value attribute, but it does not allow you to set the value from the page using only the value attribute. 

In this exercise, you'll learn how to:
  • Define a property to hold the selected value.
  • Use the selected attribute to specify the currently selected value.
  • Define a method to convert the set of countries to JSON format.
  • Use the ajax tag's value attribute to provide the data to the JavaScript component.

Defining a Property to Hold the Selected Value

A property in a managed bean includes a private variable, a method to get that value, and a method to set that value.

To add a property for the selected country, do the following:
  1. Open ComboBoxBean.java in an editor.
  2. Add the following property to ComboBoxBean.java:
    private String country = "";

    public String getCountry () {
    	return country;
    }

    public void setCountry(String country){ 
    	this.country = country;
    }
  3. Save the file.


Using the ajax Tag's Selected Attribute to Refer to the Property

Now that you have created the property, you can refer to it from the selected attribute of the ajax tag, by following these steps:

  1. Open the comboboxFaces.jsp page in an editor.
  2. Add a value and selected attributes to the ajax tag, as shown here:
    <a:ajax id="cbl" name="dojo.combobox" 
    	selected="#{ComboBoxBean.country}"
  3. Save the file.

Defining a Method to Convert the Set of Countries to JSON Format

In order to transfer the list of data to the client along with the AJAX response, you need to convert it to JavaScript.  In this exercise, you will convert the data to JSON, which is an object-oriented form of JavaScript.

To convert the countries data to JSON:

  1. Add the following completeCountry method to ComboBoxBean:
       public void countryService(FacesContext context, AjaxResult result) {
           HttpServletRequest request = 
    	(HttpServletRequest)context.getExternalContext().getRequest();
           // get the command
           String command = request.getParameter("cmd");
           result.setResponseType(AjaxResult.JSON);
           if ("setValue".equals(command)) {
               String value = request.getParameter("value");
               setCountry(value);
               result.append("[message:'success']");
           } else {
               result.append("[");
               for (int loop=0; loop < countries.length; loop++){
                   result.append("[\"" + countries[loop] + "\",\"" + 
    			countryCodes[loop] + "\" ]");
                   if (loop < countries.length -1) result.append(",");
               }
               result.append("]");          
           }
       }
  2. Save the file.

This method works like a mini-controller, which recieves the FacesContext as the first argument and an AjaxResult as the second argument. When writing a a service you have access to all the request parameters via the FacesContext. In the case of the Dojo ComboBox it will make an HTTP POST containing a parameter cmd with the value of "setValue" when an update request from the client is made. Also in the HTTP POST will be a parameter "value" with the new value. The preceding code snippet is  setting the value on the current bean. You should do any validation here. Note that because updates are occurring outside of the JavaServer Faces lifecylce, you are responsible for validationg the inputs.  In other words, you cannot use the standard JavaServer Faces validators at this time.


Pointing the ajax Tag's Value Attribute to the Data Set

Now that you have the data for the combobox available in JSON format from the managed bean, you can point to it using the value attribute of the ajax tag by performing these steps:

  1. Open the comboboxFaces.jsp page in an editor.
  2. Add the value attribute to point to the completeCountry method, which returns the data in JSON format:
    <a:ajax id="cbl" name="dojo.combobox" 
    	selected="#{ComboBoxBean.country}" 
    	value="#{ComboBoxBean.completeCountry}"/>
    In this value attribute value, ComboBoxBean refers to the name given to the bean in the faces-config.xml file, and completeCountry references the method that converts the data to JSON format.
  3. Save the comboboxFaces.jsp file.

Configuring the Managed Bean

In order to make ComboBoxBean available to the managed bean creation facility, you need to configure it in the faces-config.xml file.  To do this, perform these steps:
  1. Open the faces-config.xml file, located in the <tutorial_INSTALL>/blankFacesApp/src/resources/META-INF directory, in an editor.
  2. Add the following to faces-config.xml:
    <managed-bean>
    	<managed-bean-name>ComboBoxBean</managed-bean-name>
    	<managed-bean-class>
    		com.sun.facesApp.dojo.ComboBoxBean
    	</managed-bean-class>
    	<managed-bean-scope>session</managed-bean-scope>
    </managed-bean>
  3. Save the file.

Running the Application

Let's test our application again to see if the we can get the data from the bean and set the selected value of the combobox from the bean:

  1. Open ComboBoxBean.java and set the country to Uganda:
    private String country = "Uganda";
  2. Save the file.
  3. Make sure you have saved comboboxFaces.jsp as well.
  4. In a terminal window, go to <tutorial_INSTALL>/blankFacesApp.
  5. Run ant clean.
  6. Run ant
  7. Go to the dist directory.
  8. Redeploy the application:
    asadmin deploy blankFacesApp.war
  9. Run the application by entering this URL in your browser:
    http://localhost:8080/blankFacesApp/comboboxFaces.jsp

You should now see all the countries in the combobox, and you should see that Uganda is the selected country in the combobox.  Keep the application deployed in preparation for the next exercise.

Accessing the Widget's Value

When using jMaki widgets as JavaServer Faces components, you have a couple ways to access the widget's current value.  If you have a managed bean property that holds the value, you can use the ajax tag's value attribute to get that value, as shown in the previous secton.  If you need to get the value to make it available to other widgets in the page, you can reference a map of attribute values that the jmaki.js file maintains.  In this section, you'll learn how to use the jMaki attribute map to get the widget's value.

Getting the Selected Value from the Page

The jMaki.js file defines a map that holds the attributes of widget intances.  You can use this map to get attribute values to use them in the page.  This exercise involves using the map to get the country that the user selected from the combobox.


Using the jMaki Attribute Map to Get the Widget's Value

Perform the following steps to add a button that creates a popup window displaying the currently selected country:

  1. Open the comboboxFaces.jsp page in an editor.
  2. Add a button right after the ajax tag in the comboboxFaces.jsp page, as shown here:
    <input type="button" value="Show Selected Value" 
     onclick="alert(jmaki.attributes.get('thisForm:cb1').getValue()); 
    		return false;">
  3. Save the file.

The call to the alert function causes a popup dialog to appear when the button is clicked.  The value passed to the alert call is what is displayed in the dialog.  The return false; statement prevents a form submit from occurring.

The form tag on this page should now look like this:

<h:form id="thisForm" onsubmit="return false;">
 <a:ajax id="cbl" name="dojo.combobox" 
	selected="#{ComboBoxBean.country}" 
	value="#{ComboBoxBean.completeCountry}"/>
 <input type="button" value="Show Selected Value" 
  onclick="alert(jmaki.attributes.get('thisForm:cb1').getValue()); 
		return false;">
</h:form>

When the user clicks this button the application gets the currently selected value of the cb1 combobox and displays it in a popup dialog.


Running the Application

To test if you are able to get the selected value, do the following:

  1. You still have the application deployed, so you can copy the comboboxFaces.jsp page to the following location:
    <JavaEE_HOME>/domains/domain1/applications/j2ee-modules/blankFacesApp
  2. Run the application:
    http://localhost:8080/blankFacesApp/comboboxFaces.jsp
  3. Select a value from the combobox and click the button to see the dialog that displays the country you selected.
  4. Keep the application deployed for the next exercise.


Wrapping Up

Now you know how to use a jMaki widget as a JavaServer Faces component.  Refer to Using jMaki Widgets as JSP Tag Handlers  for information on how to respond to widget events and how to modify the styles of a widget.  You perform these tasks the same way whether you are using the widget as a JavaServer Faces component or a JSP tag handler.

Resources

JavaServer Faces Technology
X Tutup