Section 7.2. Third-Party Tag Libraries
7.2. Third-Party Tag LibrariesNow you know how to create a tag library that encapsulates your own Ajaxian features. But what about third-party tag libraries? Do such libraries exist? Yes, they do. In the rest of this chapter, we're going to look at three: AjaxTags, AjaxAnywhere, and JavaWebParts.[*] Being able to create your own tag library is valuable, but relying on someone else's expertise and experience can be even better.
7.2.1. AjaxTagsAjaxTags is a SourceForge project (http://ajaxtags.sourceforge.net) that allows you to use Ajax with minimal effort. It consists of a set of JSP tags that tie into Ajax functionality. You don't need to write JavaScript to use these tags. If you want to use some tested JavaScript and reduce your development time, AjaxTags might be the library you're looking for. AjaxTags 1.2 currently provides 10 tags, which are listed in Table 7-1. More tags may be available by the time you read this book.
One of the most interesting tags in the library is the Tab Panel tag, which is used to set up tabs in an application that displays the contents of some tables. Let's see what it takes to use that tag. Figure 7-1 shows the application we're heading toward. Figure 7-1. The Tab Panel tag displaying user information from the database When you click on a tab, the browser requests the data to populate the tab. Clicking on the Shopping Carts tab displays all the items currently in the shopping cart, and clicking on the Products tab displays all the products in the database. 7.2.1.1. Getting and installing AjaxTagsTo get started, go to http://ajaxtags.sourceforge.net, locate the current version of AjaxTags in the Downloads section, and download it. The AjaxTags project will probably come as a zipped archive for Windows and a tar archive for Linux. Uncompress the archive, find the ajaxtags.jar file, and copy it into your WEB-INF/lib directory. The .jar file will probably be in the dist directory and should be named ajaxtags with the version appended to it (e.g., ajaxtags-1.2-beta2.jar).
Next, copy ajaxtags.tld into the WEB-INF directory and add the taglib definition to the web.xml definition file in WEB-INF, as follows: <taglib> <uri>http://ajaxtags.org/tags/ajax</uri> <location>/WEB-INF/ajaxtags.tld</location> </taglib> 7.2.1.2. Using the <tabPanel> tagTo use a tab panel, put the <ajax:tabPanel> tag in the JSP, as shown in Example 7-9. The <tabPanel> tag sets up a set of tabbed panels. You must define each tab that you would like your page to display within the <ajax:tabPanel> with an <ajax:tab> tag. The <ajax:tab> takes caption, baseUrl, and parameters attributes as input. The tabs display the labels defined by their caption attributes. The baseUrl parameter provides the address of the web service that handles the call (in our case, /tabcontent), and you can use the parameters parameter to set the request parameter for a tab. You can also select one tag in the set to be the default; to do so, set defaultTab="true". Example 7-9. index.jsp uses AjaxTags to produce a tab panel
Notice that the Users tab does not have a parameters attribute. That is to illustrate that the parameters attribute is not required and that the tab's request parameters can be passed in the baseUrl attribute, as in /tabcontent?tab=Users. In addition to including the tag library ajaxtags.tld and the two JavaScript library files prototype-1.4.0.js and ajaxtags.js, the index.jsp page links to an important support file, ajaxtags-sample.css. The CSS support file comes with the AjaxTags demo application. The tabs rely heavily upon these support files. To get them, go to http://ajaxtags.sourceforge.net/index.html and download the Demo War files. The CSS files will be in the web/css directory. (You can customize these files later if you like; the downloadable versions just provide a starting point to get your applications working.) 7.2.1.3. Writing the servlet codeOnce you've created the JSP for your tabbed panel, you need a servlet to respond to the Ajax requests generated by the tabs. The response should be an HTML-formatted string to fill the div for each tag. We'll call our servlet TabContentServlet. The TabContentServlet must return text for the tab that has been selected. This servlet must extend BaseAjaxServlet and override the getXMLContent( ) method. (BaseAjaxServlet is provided by the AjaxTags project and can be found in its JAR file.) The servlet pulls the parameter tab from the request and uses it to see which tab is requesting content. For this application, a simple if/else block will suffice for the controller. The TabContentServlet code is shown in Example 7-10. Example 7-10. The TabContentServlet
The value for the tab parameter was set up in our JSP, as part of the request URL. For example, the Users tab includes the tab=Users pair at the end of the URL: <ajax:tab caption="Users" baseUrl="${pageContext.request.contextPath}/tabcontent?tab=Users" defaultTab="true"/> 7.2.1.4. Displaying data in the tabsThe next step is to pass formatted data back to the tab for display. I feel squeamish about returning a formatted HTML string from the model, which should not have to deal with formatting issues. For this application, however, it is the best course. The Tab Panel tag in the AjaxTags library expects the contents of the tabs to be returned as formatted HTML. The alternative is to return the data in a format that JavaScript can parse, but that would add a lot of complexity. If you are writing a more sophisticated application and must separate the model from the formatting details, you can simply return the object as an XML or JSON string and either parse and format the details in JavaScript or switch to Struts and use the bean.tld that Struts provides. Example 7-11 presents the method that returns the HTML for the Users tab. The HTML is simple because most of the heavy-duty formatting is handled by the CSS. Therefore, getUsersView( ) only needs to generate the <table>, <td>, <tr>, and <th> tags. The properties are limited to CSS class names, which allows you to manipulate much of the formatting from the CSS file. Example 7-11. Excerpt from UserManager.java
getUsersView( ) establishes a connection with the database and performs a query to get the information about the users; the results are then parsed and formatted into an HTML string. The class property of each HTML element is given a different name, so you can control most of the formatting in an external CSS file, without touching the Java code. This makes for as clean a separation as possible when using the AjaxTags library. Data for the other tabs is managed with similar methods. The view for the Shopping Cart tab is managed with a call to getShoppingCartView( ), as shown in Example 7-12. Example 7-12. The getShoppingCartView( ) method of ShoppingCartManager
Except for the query, this method is similar to getUsersView( ). Both methods use an index value in the while loop to tag every other row with a different CSS class. This allows you to make the contents of the tabbed panel more readable by giving alternate rows different looks. The most common way to do this is to give every other row a gray background: if (index++ % 2 == 0) cartclass = "CartLight"; else cartclass = "CartDark"; The getProductsView( ) method, presented in Example 7-13, gets product information from the database and sends it to the Products tab as an HTML string. Example 7-13. The getProductsView( ) method
There's nothing particularly new or notable here; this method is similar to getUsersView( ) and getShoppingCartView( ). We've dispensed with using alternating CSS tags, though, so you can't change the background color of every other row to make the tab's contents more readable. The CSS code for this example was embedded in the JSP, but it should eventually be put into another file, especially if the application is going to see a production environment: <style> Table.Product {border: solid 2px; border-color:#CCFF66;} TD.Product{background-color:#CCCCFF;border: solid 2px; color:#000099} TH.Product{background-color:#000099; color:#CCCCFF} Table.User {border: solid 2px; border-color:#CCFF66;} TR.UserDark {background-color:#CCCCFF;border: solid 2px; color:#6666CC} TR.UserLight {background-color:#CCFFFF;border: solid 2px; color:#6666CC} TH.User {background-color:#6666CC; color:#CCCCFF} Table.Cart {border: solid 2px; border-color:#339966;} TR.CartLight {background-color:#CCCCFF;border: solid 2px; color:#336666} TR.CartDark {background-color:#33FF99;border: solid 2px; color:#336666} TH.Cart {background-color:#336666; color:#CCCCFF} </style> The CartLight and CartDark values for Table.Cart are not used because the Java code does not tag anything with those classes. The final step is to add the definition of TabContentServlet to the web.xml file: <servlet> <servlet-name>tabcontent</servlet-name> <servlet-class>com.oreilly.ajax.servlet.TabContentServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> <servlet-mapping> <servlet-name>tabcontent</servlet-name> <url-pattern>/tabcontent </url-pattern> </servlet-mapping> After you implement this demo, try changing the data in the database and then switching through the tabs to see how each panel is updated. One great thing about using Ajax in an application like this is that real-time updates occur as you shift through the tabs, without any browser caching issues. 7.2.2. JavaWebPartsJavaWebParts is a large library comprised of many separate components. See the documentation at http://javawebparts.sourceforge.net for the latest information on JavaWebParts. The documentation is very sparse, but it gives you an idea of what's available. The SourceForge forum is also useful; Frank Zametti, one of the core developers of the Ajax-enabled tags, is active in answering questions about using those tags. No JavaScript programming is required to use the JavaWebParts library. You simply insert the tags you need into a JSP and then write the server-side support for those tags in Java. If you're not a fan of JavaScript, this approach has obvious advantages, but the drawback is that you are limited to the tags that have been implemented. Table 7-2 summarizes the JavaWebParts components. Note that there are many different kinds of components available, not just components implementing Ajax features. They're all worth investigating.
Rather than providing a library of Ajax-enabled components, JavaWebParts takes a more general approach. Instead of a specific tag with a specific name, you place a generic tag, <ajax:event>, after the HTML element that you want to trigger an Ajax event. Then you connect up that event in a configuration file, which is normally called ajax_config.xml. To demonstrate how to use JavaWebParts, we'll look at an application that uses Ajax to populate one select field based on the selection in another select field. Figure 7-2 shows the application we're working toward. Figure 7-2. Populating one select field based on the selection in another The JSP for this application sets up the select fields so that when the user selects a state, a request is sent to the server, which returns a list of cities in that state. That list is used to fill a <div>, which in turn populates the "Cities:" select field. It starts with a taglib directive that loads the JavaWebParts tag library. The JSP uses only two Ajax-specific tags: <ajax:event>, which follows the state selection box, and <ajax:enable />. Other than that, as you can see in Example 7-14, the JSP contains no extra code to indicate that this is an Ajax-enabled web page. Example 7-14. index.jsp
The <ajax:enable /> tag injects the JavaScript that will support the Ajax calls to the server. To see what code <ajax:enable /> produces, load the page in your browser and look at its source. You should see something similar to the following: <script> var calls = new Array( ); var pendingResponseCount = 0; var shouldDebugAjax = false; var assureUnique = 1; function ajaxRequestSender(form, target, qs, dom, resHandler, resHandlerParam, method, async, mungedRef, timerObj, ajaxRef) { ... } function onResponseStateChange(callKey) { ... } function createXMLHttpRequest( ) { var xmlHttpRequest; if (window.XMLHttpRequest) { return new XMLHttpRequest( ); } else if (window.ActiveXObject) { return new ActiveXObject('Microsoft.XMLHTTP') } } </script> The ajax_config.xml file contains the information to set up the tags that are used in the JSP. The ajaxRef attribute of the <form> tag specifies the name given to the form in the JSP (in this case, "StateSelectForm"): <ajaxConfig> <form ajaxRef="StateSelectForm"> <element ajaxRef="stateSelectionChange"> <event type="onchange"> <requestHandler type="std:QueryString" method="get"> <target>JWPSelectServlet</target> <parameter>state=stateSelected</parameter> </requestHandler> <responseHandler type="std:InnerHTML"> <parameter>cities</parameter> </responseHandler> </event> </element> </form> </ajaxConfig> Within the form, <ajax:event> tags determine which elements trigger Ajax events; within the configuration file, the <element> tag with its ajaxRef attribute specifies the element whose events we're mapping (in this case, the stateSelectionChange element within the StateSelectForm). The <ajax:event> tag in the form has an ajaxRef attribute of "StateSelectForm/stateSelectionChange". Back in the configuration file, the type attribute of the <event> tag specifies what kind of events we're looking for (here, onchange events). So, putting it all together, we're looking for onchange events coming from the stateSelectionChange element within the StateSelectForm. The next two elements within the <event> tag specify what to do with these events when they arrive. The <requestHandler> tag connects the Ajax request to a handler (in this case, our servlet). This tag also specifies that the JSP will make a "get" request to the JWPSelectServlet, which is the <servlet-mapping> configured in web.xml. In order to pass data back to the servlet, we need to pass request parameters. The <parameter> tag defines those parameters. In this case, we're passing a key/value pair in a GET request. The name of the key is state; its value is from the element in the JSP with the id stateSelected. Finally, the <responseHandler> tag sets up the JSP to handle the response from the servlet. The servlet sends HTML text, which is inserted into the JSP element with an id of cities using the innerHTML method. The cities parameter is wrapped in the <parameter> tag. The web.xml file (shown in Example 7-15) must include the <context-param> tag, which sets the ajaxTagsConfig file to /WEB-INF/ajax_config.xml. web.xml also configures a listener for incoming events (the AjaxInit class) and the servlet that processes the events, and returns the data back to the client (JWPSelectServlet). Example 7-15. The web.xml file that sets up JavaWebParts
We've now connected the listener and the configuration file and configured the servlet that will send the data back to the JavaWebParts tags. The code for this servlet is presented in Example 7-16. Example 7-16. The JWPSelectServlet
The servlet builds a list of cities for the selected state, wraps each city name with an <option> tag, and then sends the results back to the form, where they are placed in the element specified by the ajax_config file.
JavaWebParts provides many tags and features that you can add to your applications. Its design is relatively flexible; rather than providing components with fixed functions, it provides capabilities that you can integrate into your applications. Its main disadvantage is that there is limited documentation, and you must live with the way the features work unless you are willing to fix and contribute to the project. JavaWebParts is an active project that's constantly undergoing revision and improvement; I suspect it will continue to evolve into a valuable addition to the Ajax toolkit. 7.2.3. AjaxAnywhereThe AjaxAnywhere project has been available on SourceForge since September 2005. It provides a browser-independent JavaScript API for sending data to a server via XMLHttpRequest. Once data has been sent to the server, AjaxAnywhere uses the response to update "zones" in your web application with the returned data. A zone can be any HTML element that can take an id, such as a <div>. To start, visit the home page of AjaxAnywhere at http://ajaxanywhere.sourceforge.net, look at the documentation, and download the library (a .jar file). The server-side application calls the static method AAUtils.addZonesToRefresh( ) to configure which zones are to be updated. This method is usually called in a servlet or JSP. The servlet sends data back to the JSP containing the zone or zones to be updated; a filter intercepts the response and converts it to XML that contains only the HTML needed to update the client. The client receives the XML and updates the zone or zones selected for refresh. In this section, we'll look at an application that contains two select elements, the first of which is populated with a list of states (Figure 7-3). After the user clicks on a state, the second select area populates with a list of the cities in that state. Then, if the user clicks on one of the cities, the third area populates with a listing of all the states in which a city by that name is found. The code for the application will illustrate how to look up an item and then execute a reverse lookup on the result. I wanted to demonstrate this capability of AjaxAnywherespecifically, the ability to dynamically insert Ajax triggersbecause it is not currently supported by JavaWebParts. Figure 7-3. AjaxAnywhere Demoselect a state, then a city When the user clicks one of the states in the State list, the browser sends a call to the AjaxAnywhereSupportServlet. The servlet determines which field has been sent by calling request.getParameter( ). The appropriate zone is configured with a call to AAUtils.addZonesToRefresh( ), and the data needed for that zone is stored as an object in the session. With this data, the browser displays a list of cities that are in the selected state in the second select field. After the user selects a city, the browser displays a list of all the states in which a city with that name is found in the box on the right. So far, we've said that the servlet handling the request stores the data needed to update a zone in the session. How does that update happen? To do the refresh, we can use either Java in a JSP, or the AjaxAnywhere JavaScript API. For this example, we'll use Java code in the JSP. 7.2.3.1. Enabling AjaxAnywhere in the JSPThe AjaxAnywhere implementation in index.jsp is presented in Example 7-17. Example 7-17. AjaxAnywhere implementation in index.jsp
The first bit of code pulls a couple of ArrayList objects (the cityList and stateList) from the session. The first time through, these ArrayLists will be null; eventually, they will be used to populate the different select fields. We then import the AjaxAnywhere JavaScript library, aa.js: <script src="/books/4/163/1/html/2/aa.js"></script> This library provides support for the AjaxAnywhere tag library, including the submitAJAX( ) function. Next, we initialize the variable ajaxAnywhere.formName with the name of the form that will be submitted by the call to submitAjax( ): <script>ajaxAnywhere.formName = "main";</script> Then we set the JavaScript onchange trigger to call submitAJAX('function=state'): <select size="10" name="state" onchange="ajaxAnywhere.submitAJAX('function=state');"> Now when the selection is changed, AjaxAnywhere submits the form via XMLHttpRequest, passing in the request parameter function=state. So, an XMLHttpRequest is generated whenever the user selects a state. Further down in the JSP there is another call to submitAjax( ), this time with the parameter 'function=city': <select size="10" name="city" onchange="ajaxAnywhere.submitAJAX('function=city')"> This call generates the XMLHttpRequest when the user selects a city. 7.2.3.2. Refresh zonesTo understand AjaxAnywhere, you must understand the concept of refresh zones. A refresh zone is contained between <aa:zone> and </aa:zone> tags and contains the area that AjaxAnywhere will update when the AjaxAnywhere servlet sends back its response. (Configuring this servlet will be discussed in more detail later.) When the servlet sends back the response to a submitAjax( ) call, the Java code inside the <aa:zone> tag that is targeted for refresh is executed. (Note that this is the only time we've seen Java code, rather than JavaScript, used to update HTML components.) So, in this case, the servlet calls AAUtils.addZonesToRefresh( ), specifying that it wants to refresh the citiesList zone. When the response comes back, the Java code on lines 5064 populates the city selection box with options taken from an ArrayList that was stored in the session. Similar code on lines 7185 populates the list of states on the right side of the window after the user selects a city. Again, this code executes only when the servlet has called AAUtils.addZonesToRefresh( ) to target the stateswcityList zone for refresh. 7.2.3.3. Writing support for AjaxAnywhereNow that we've looked at the JSP that creates the HTML the browser renders, let's look at the AjaxAnywhereSupportServlet. This servlet must be written by the developer to support AjaxAnywhere for a specific application; it is not part of the AjaxAnywhere package. The AjaxAnywhereSupportServlet (Example 7-18) handles the XMLHttpRequests sent by the browser. First, the servlet verifies that the requests have come from an AjaxAnywhere application by calling AAUtils.isAjaxRequest( ). If this method returns true, the servlet goes on with the rest of the processing. If it isn't dealing with an AjaxAnywhere request, there's clearly no point in dealing with zones and the rest of the AjaxAnywhere mechanism. Example 7-18. The AjaxAnywhereSupportServlet
If the call to AAUtils.isAjaxRequest( ) returns true, the servlet decides whether to update the list of states or the list of cities, depending on the value of the function parameter that submitAjax( ) added to the request URL. If the value of the function parameter is "city", we're being asked for a list of states that match the city included in the request. In this case, the servlet first calls AAUtils.addZonesToRefresh( ) to say that it is updating the stateswcityList zone. It then calls the getStates( ) method, which returns an ArrayList of states that contain a city of the given name. This list is then added to the session, under the stateList attribute. The logic is similar if a list of cities is requested (i.e., if the value of the function parameter is "state"): the servlet states that it wants to update the citiesList zone and calls getCities( ) to find the list of cities in the given state, and then this ArrayList is added to the session under the cityList attribute. Why not just check for a null value in either the city or the state? That seems logical, but doing so would constitute an error. If you look back at the JSP code in Example 7-17, you will see that both zones are in the same form. That means that the request will always have a state and a city parameter. This makes it difficult to use those parameters as a way to determine which one was actually passed in fresh. Once all the hard work is done, the servlet gets the ServletContext, uses the context to get the RequestDispatcher, and then uses the RequestDispatcher to send the response back to index.jsp. The AjaxAnywhereSupportServlet has two other methods that help it get the data for the cities and states. The getCities( ) method, presented in Example 7-19, returns a collection of strings containing all the cities for a given state. Example 7-19. The getCities( ) method
The other method that AjaxAnywhereSupportServlet needs is getStates( ), presented in Example 7-20, which returns a collection of strings containing the names of all the states in which a city with the given name is found. Example 7-20. The getStates( ) method
7.2.3.4. The AjaxAnywhere filterThe last thing we need to do before we can get the application up and running is to configure the AjaxAnywhere filter. This filter formats the code coming from the servlet to trigger zone updates. When I first began writing this section, I neglected to add a filter mapping for the servlet, and it took me a while to figure out why the application was not working. The lesson to be learned is to make sure that you have the filter mapping configured correctly in web.xml! The web.xml file in Example 7-21 contains examples of the different filter mappings that can be used for AjaxAnywhere. The only filter mapping that is actually needed is the one that maps AjaxAnywhere to /AjaxAnywhereSupport; the others have been left in for illustrative purposes. Example 7-21. web.xml with servlet and filter mappings for AjaxAnywhere
The AjaxAnywhere tag library is a very flexible tool for building sophisticated Ajaxian applications. Don't expect to find ready-made Ajax applications in this library, but do expect to find some very useful ways to add Ajax to an existing or new application, with hardly any knowledge of JavaScript. 7.2.4. Which Tag Library Should I Use?Good question. I've tried to cover the major Ajax tag libraries here. None is a clear winner; each has its place. If you find a component like the Tab Panel in AjaxTags to be useful, use AjaxTags in your project. If you find a component in JavaWebParts to be useful in your code, use JavaWebParts. If you don't need a specific component, but want to have the freedom of writing Ajax-enabled code without JavaScript, try using AjaxAnywhere. The bottom line is to use whatever benefits your project the most. Now that you have seen what each tag library can do, you are in a position to choose wisely. And of course, if you want to reuse your code as tags and you can't find a tag library that works for you, you can always write your own tag library. But if you do this, try to contribute the result to one of the existing projects so our programming community can benefit. The Java community needs more collaboration, fewer libraries, and more features in each library. Then we can spend less time learning the various libraries and more time implementing their features in our code. |
