Using the Sack Framework

The Sack Ajax framework is a popular one, and it’s also free and ready to download.

On the Web

Sack, which stands for Simple Ajax Code Kit, is available for free at http://twilightuniverse.com/resources/code/sack/. The actual JavaScript librarythat you use is called tw-sack.js.

Here are the main functions you use with the Sack framework:

sack: Initializing function for the Sack object
- Use: object sack(file)

file (optional): The name of the file to be accessed using XMLHttpRequest
setVar: Enables you to add data to the URL in the form of a name/value pair. Does not encode the data
- Use: void setVar(name, value)

name: The name of the data that you want passed
value: The corresponding data that you want passed
runAJAX: Runs the AJAX request and fills class variables with appropriate responses
- Use: string runAJAX(url)

url (optional): A string of name/value pairs formatted in the GET URL String style (for example, var1=data1&var2=data2)

Here’s an example, testSack.html, that reads and downloads the file sack.txt, which has these contents on the server:

 This text was downloaded with Sack.

The testSack.html page starts with a “Display the text” button, connected to a JavaScript function named useSack:

 <H1>Testing the Sack framework</H1> <form>   <input type = "button" value = "Display the text"      onclick = "useSack()"> </form>

And there’s also a <div> element in which to display the downloaded text:

 <H1>Testing the Sack framework</H1> <form>   <input type = "button" value = "Display the text"     onclick = "useSack()"> </form> <div >   <p>The fetched data will go here.</p> </div>

You have to include the Sack JavaScript library as well, of course, and that’s tw-sack.js:

 <html>   <head>     <title>Testing the Sack framework</title>     <script src = "tw-sack.js"></script>         .         .         .

You also add the useSack function, which is connected to the button in this Web page:

 <html>   <head>     <title>Testing the Sack framework</title>     <script src = "tw-sack.js"></script>     <script language = "javascript">       function useSack()       {         .         .         .       }     </script>

Next, create a Sack object, using the initializing function named sack like this:

 <html>   <head>     <title>Testing the Sack framework</title>     <script src = "tw-sack.js"></script>     <script language = "javascript">       function useSack()       {         var sackObject = new sack();         .         .         .       }     </script>

To use Sack, configure the Sack object and then call its runAjax method. Configure the Sack object by setting the following properties:

AjaxFailedAlert: Holds a warning message used to alert users that their browser does not support XMLHttpRequest objects. To turn off the warning, set this property to null. Contains a default warning message.
element: The element whose contents should be replaced with the contents of the response text.
encodeURIString: Set to true/false; indicates whether to escape the data in the URL string. Set to false to escape the text yourself. The default is true.
execute: Set to true if you want to evaluate the response text as if it was JavaScript code and run it. The default is false.
failed: Allows you to detect whether the software supports XMLHttpRequest objects (true) or not (false).
method: Sets the HTTP method used to communicate with the URL. You can use any valid method; GET and POST will probably be most common. The default is POST.
onCompletion: Set this property to a JavaScript function (without arguments) that you want to run when the download is completed.
onInteractive: Set this property to a JavaScript function (without arguments) that you want to run when the code is connected to the server.
onLoaded: Set this property to a JavaScript function (without arguments) that you want to run when the data has been downloaded.
onLoading: Set this property to a JavaScript function (without arguments) that you want to run when the data is downloading.
requestFile: Set to the URL that the request will be sent to.
response: Contains the response text sent from the server.
responseStatus: An array of the response status returned. 0 index is the response code (for example, 404, 300, and so on) and the 1 index is the text description.
responseXML: Contains the response XML received from the server.
URLString: Contains a list of parameters and values in name/value pairs.

For example, to download the file sack.txt, set the Sack object’s requestFile property to sack.txt:

 <html>   <head>     <title>Testing the Sack framework</title>     <script src = "tw-sack.js"></script>     <script language = "javascript">       function useSack()       {         var sackObject = new sack();         sackObject.requestFile = "sack.txt";         .         .         .       }     </script>

You can also set the HTTP method to use when communicating with the server to GET using the Sack object’s method property:

 <html>   <head>     <title>Testing the Sack framework</title>     <script src = "tw-sack.js"></script>     <script language = "javascript">       function useSack()       {         var sackObject = new sack();         sackObject.requestFile = "sack.txt";         sackObject.method = "GET";         .         .         .       }     </script>

In fact, you can even specify the HTML element whose content should be replaced with the downloaded text. In this example, that’s the targetDiv element, so you can tell Sack to place the downloaded text in the targetDiv element like this:

 <html>   <head>     <title>Testing the Sack framework</title>     <script src = "tw-sack.js"></script>     <script language = "javascript">       function useSack()       {         var sackObject = new sack();         sackObject.requestFile = "sack.txt";         sackObject.method = "GET";         sackObject.element = "targetDiv";         .         .         .       }     </script>

All that’s left is to call the Sack object’s runAjax method, passing it an empty string so it won’t send any data to the server:

 <html>   <head>      <title>Testing the Sack framework</title>      <script src = "tw-sack.js"></script>     <script language = "javascript">       function useSack()        {          var sackObject = new sack();         sackObject.requestFile = "sack.txt";         sackObject.method = "GET";          sackObject.element = "targetDiv";         sackObject.runAJAX("");       }     </script>

That’s all you need. Sack takes it from here, downloading sack.txt and displaying the contents of that file in the target <div> element. You can see testSack.html at work in Figure 6.3. Click the button to see this example download sack.txt and display the contents of that file.

image from book
Figure 6.3: Downloading text with the Sack Ajax framework