Example 1: Hello World!
This is as easy as it gets: A simple, parameter-less Ajax request, with a simple server response. This example doesn't do anything exciting, but be sure to read this tutorial and study the code closely, as it lays the foundation for using Taconite.
The XHTML Page
Listed below is the client HTML page. Note that there is just a link on the page. Clicking it sends an Ajax request to the server, and the server's response is appended to the page. Below the code for the HTML page, and the explanation follows.
01 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
02 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
03
04 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
05 <head>
06 <title>Taconite Example</title>
07 <script type="text/javascript" src="/taconite-examples/js/taconite-client.js"></script>
08 <script type="text/javascript" src="/taconite-examples/js/taconite-parser.js"></script>
09
10 <script type="text/javascript">
11 function doHelloWorld(url) {
12 var ajaxRequest = new AjaxRequest(url); //Create AjaxRequest object
13 ajaxRequest.sendRequest(); //Send the request
14 }
15 </script>
16 </head>
17 <body>
18 <br/>
19 <br/>
20 <a href="javascript:doHelloWorld('example1-all.jsp');">Hello World</a>
21
22 <br/><br/>
23 <div id="helloWorldContainer">
24
25 </div>
26 </body>
27 </html>
As you can see, it's a pretty spartan page. Let's take a look at the Taconite bits.
Lines 7 and 8 reference Taconite JavaScript files. The taconite-client.js defines the AjaxRequest object, which is the heart of the Taconite client-side library. The taconite-parser.js file references the JavaScript-based Taconite parser, that performs the XHMTL-to-DOM parsing on the browser.
Lines 18 and 20 define the links that initiate the Ajax request when clicked. Each link calls the doHelloWorld function, passing to it the URL of the Ajax service to be called.
Line 23 defines an empty div element with an id attribute value of helloWorldContainer. This is very important. This div is the location to where the server's response will be appended. We'll discuss this more when we look at the server side components.
Lines 11-14 define the doHelloWorld function. Thanks to the Taconite framework, it's only two lines long. The first line creates an instance of the AjaxRequest object. The AjaxRequest object, as described by its name, encapsulates an Ajax request. Each instance of an AjaxRequest object creates its own instance of the XMLHttpReques object, so you can create as many as you'd like (or that your browser will support) and note have to worry about instances of XMLHttpRequest overwriting one another.
The AjaxRequest object is created by passing single argument to the object constructor. The argument is the URL to which the Ajax request will be sent. In this example, the URL is one of two JSPs, as defined by the two links on the page.
The second (and last!) line of the doHelloWorld function sends the request to the server. The AjaxRequest object defines a sendRequest method which is called here to send the request. And that's it! The rest is defined on the server, which we'll look at next.
So far so good, right? With the help of Taconite, this Ajax stuff is a breeze!!
Writing the Server Response
Clicking either of the links on the page should append a "Hello World!" message to the page. Thanks to Taconite, this is easily accomplished by simply specifying the XHTML that renders the "Hello World" message.
Taconite's response is always XML. The XHTML that will render the "Hello World" message must be embedded in some Taconite-specific XML tags.
Listed below is the source code for the example1-all.jsp file. This demonstrates how to write a Taconite response "by hand", using Taconite XML tags.
01 <%@page contentType="text/xml"%>
02
03 <taconite-root xml:space="preserve">
04
05 <taconite-append-as-children contextNodeID="helloWorldContainer">
06
07 <div style="font-weight:bold;color:orange;">
08 Taconite says: Hello World!!!
09 </div>
10
11 </taconite-append-as-children>
12
13 </taconite-root>
We'll start at the top. At Line 1 is a JSP directive indicating that the Content-Type of the page should be returned as text/xml. All Taconite responses must be returned with a Content-Type of text/xml, otherwise the XMLHttpRequest object won't be able to parse it as an XML document. This is the only JSP-specific line in this file, so to reproduce this file using any other server-side technology, simply be sure to set the Content-Type to be text/xml.
Line 3 has the taconite-root XML tag, which is the root tag of all Taconite responses. All Taconite responses must have the taconite-root tag as the root tag. The presence of this tag ensures that the response is well formed XML. The matching closing tag is on Line 13. Note that the taconite-root tag has a attribute of xml:space="preserve". This is to ensure that Internet Explorer handles whitespace correctly. To ensure that IE handles whitespace correctly, always add this attribute to the taconite-root tag.
Line 5 opens the taconite-append-as-children tag. This tag says that the child elements of this tag will be appended as children to the context node. The context node is specified by the contextNodeID attribute. The value of this attribute must correspond to some element on the XHTML page. Remember the empty div element on Line 23 of the XHTML page, that had an id attribute value of helloWorldContainer? This is where the message will be appended, because the contextNodeID attribute of the taconite-append-as-children tag has a value of helloWorldContainer. The second attrbute on the taconite-append-as-children tag is parseInBrowser, which has a value of true (when not using the JSP tags, parseInBrowser must always be true). This tells the AjaxRequest object that it needs to parse the response into JavaScript before running the JavaScript to produce the "Hello World" message. The matching closing tag for the taconite-append-as-children tag is on Line 11.
Finally, the "Hello World!" message is defined on Lines 7-9. Notice how the message is simply defined as valid XHTML. In fact, the div tag even has an embedded style that makes the message font orange in color! This is the beauty of Taconite: you simply specify the new or updated content as regular ol' XHTML, and Taconite does the rest, without resorting to using the pesky innerHTML property.
Is That It?
Yup, that's it! Once the server response is sent, the AjaxRequest object retrieves the response XML from the XMLHttpRequest object, then evaluates the response to produce the desired content. Only four lines of JavaScript code on the XHTML page, 13 lines for the response (5 of which are blank lines) and this page has been Ajax-enabled!