VSAL: The Very Simple Ajax Library

VSAL is the acronim of Very Simple Ajax Library. Some function of this library contain code that is not totally "flour of my sac" (An italian idiom to say that I've made a little "cut and copy" somewhere from the Internet!!!), but is a collection of pieces of code found here and there that I gathered together into something usable in a practical way. This javascript library contain some useful functions that can be used to make AJAX call without to have to know the ajax basics. Simply include the library on your HTML code define a division where to put the result and make the call! VSAL contain a total of four group of function: Utility functions, Asyncronous call functions, Syncronous call functions and functions to load XML file.

Going into details:

But not too much!

Now we'll take a look at the four groups of functions:

UTILITY:
- vsal_get_url_vars() : This function extract URL parameters returning an associative array;
- vsal_require_https() : Force to load a page using HTTPS instead of HTTP;
- vsal_please_wait(destdiv, animated_gif) : Generate a waiting effect using an animated GIF (somewhere existing!), the GIF will be loaded into the "destdiv" division;
- vsal_getFormData(obj) : This function takes as input an object of type Form and returns a string like: fieldname1=value1&fieldname2=value2&...&fieldnameN=valueN&THEEND=TRUE that can be transmitted via an AJAX request as parameter "parameters" of the functions described below.

ASYNCHRONOUS Function:
- vsal_async_get_alert(baseurl, parameters) : Makes an AJAX Asynchronous GET request and present the result within an alert window;
- vsal_async_get(baseurl, parameters, destdiv, creatediv) : Makes an AJAX Asynchronous GET request and present the result within an existing division "destdiv" or create it in-place if "creatediv" is set "true";
- vsal_async_post(baseurl, parameters, destdiv, creatediv) : Makes an AJAX Asynchronous POST request and present the result within a division "destdiv" or create it in-place if "creatediv" is set "true";

SYNCHRONOUS Function:
- vsal_sync_get(baseurl, parameters) : Makes an AJAX Synchronous GET request and return text only response;
- vsal_sync_post(baseurl, parameters) : Makes an AJAX Synchronous POST request and return text only response;

XML File Loading Function:
- vsal_load_xml(baseurl, parameters) : Load an XML file and return an XML DOM Object.

Importing the library:

To use the library simply import it in your html document with a <script></script> tag.

EXAMPLE:

<html>
<head>
...
  <script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>
...
</head>
<body>
 ... 
</body>
</html>

Usage Example:

Now we present some example on how to use the various function:

EXAMPLE 1 - Using vsal_get_url_vars:

<html>
<head>
 <title>EXAMPLE 1 - Using vsal_get_url_vars</title>
  <script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>

</head>
<body>
  <button onclick="document.location=document.location+'?param1=Hello&param2=world';">Click me</button>
  <br/>

  <script type="text/javascript">

    var params = vsal_get_url_vars();

    for(var item in params) {
     var val = params[item];

     document.write("Params["+item+"] = "+val+"<br/>");
    };

    if (params.param1) {
     document.write("Param 1 is present!<br>");

    };

    if (params["param2"]) {
     document.write("Param 2 is present!<br>");
    };

  </script>
</body>

</html>

In a real case, generaly you know the parameters the user can pass to the page, so you don't need to list all the passed parameters with a for loop, but simply you can check directly if the parameter of interest is set or not! Otherwise, unfortunately, you cannot use the "length" property, that is valid for arrays but not in this case! because, for example, firefox treat Array created with "new Array()" as Object! and so the "length" property is invalid and will return an unespected value, usually zero! But on the other hand if, for example, to your page can be passed a fixed number of parameters then you can directly access them with the dot notation EX: params.P1 or with the classic associative array notation EX: params["p1"] .

EXAMPLE 2 - Using vsal_require_https:

<html>
<head>
 <title>EXAMPLE 2 - Using vsal_require_https</title>
 <script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>

</head>
<body onload="vsal_require_https()">
  <script type="text/javascript">
    vsal_requuire_https();
  </script>
  ...

</body>
</html>

There is no problem in calling the function multiple times. You can invoke the function where you wish, but it's best to do that at the beginning of the <body> tag or using the onload event. Obviously your web server must support HTTPS. For example, my host does not support it!

EXAMPLE 3 - Using vsal_please_wait:

<html>
<head>
 <title>EXAMPLE 3 - Using vsal_please_wait</title>
 <script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>

</head>
<body>
 <button onclick="vsal_please_wait('dest','http://www.zallocco.net/images/stories/pleasewait.gif')">Click me</button>
 <br/>
 <div id="dest">I am a Division!</div>

</body>
</html>

This is a very simple functions that don't need too many explainations!

EXAMPLE 4 - Using vsal_async_get_alert:

<html>
<head>
 <title>EXAMPLE 4 - Using vsal_async_get_alert</title>
 <script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>

</head>
<body>
 <button onclick="vsal_async_get_alert('http://www.zallocco.net/vsal_test_get.php','message=Hello&To=World')">Click me</button>
 <br/>

</body>
</html>

As you can see when you press the button we invoke the "vsal_async_get_alert" function that call the "vsal_test_get.php" procedure with two parameters: "message" and "to". The vsal_test_get.php procedure simply make a dump of "$_GET" a PHP predefined array that contain all the parameters passed on the URL and then with the method GET of HTTP protocol.

NOTE: Please note that exist a limitation on the maximum number of characters that can be passed via URL depending on the HTTP protocol used by the HTTP Server, by the browser and by the scripting language used on the server side. The specification for URL length does not dictate a minimum or maximum URL length, but implementation varies by browser. On Windows: Opera supports ~4050 characters, IE 4.0+ supports exactly 2083 characters, Netscape 3 -> 4.78 support up to 8192 characters and Netscape 6 supports ~2000. So it would be good thing to put always, as the last parameter, a spy parameter like this: &THEEND=TRUE and always check, on the server side, if this parameter is arrived so to be sure that all the others parameters are arrived properly without being truncated.

EXAMPLE 5 - Using vsal_async_get with an existing DIV:

<html>
<head>
 <title>EXAMPLE 5 - Using vsal_async_get with an existing DIV</title>
 <script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>

</head>
<body>
 <button onclick="vsal_async_get('http://www.zallocco.net/vsal_test_get.php','message=Hello&To=World','dest',false)">Click me</button>
 
<br/>
<div id="dest">I am a Division!</div>
<script type="text/javascript">

  vsal_please_wait('dest','http://www.zallocco.net/images/stories/pleasewait.gif');
</script>
</body>
</html>

In this example we define a division called "dest" where we will put the result from the "vsal_test_get.php" invocation. As you can see we also use the "vsal_please_wait" function to have a loading in progress effect until the result will be arrived to the browser!

Warning! between the parameters passed to the procedure "vsal_test_get.php" (by all the vsal function) there will always be the "nocache" parameter, that serving to avoid that requests are cached by the browser.

EXAMPLE 6 - Using vsal_async_get with a "New" DIV created in place at run time:

<html>
<head>
 <title>EXAMPLE 6 - Using vsal_async_get with a New DIV created in place at run time</title>
 
<script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>
</head>

<body>
<div id="dest1">I am an existing Division!</div>
<script type="text/javascript">

  vsal_async_get('http://www.zallocco.net/vsal_test_get.php','message=Hello&To=World','dest2',true);
</script>

<div id="dest3">I am an existing Division too!!</div>
</body>
</html>

Unlike the previous example, here the destination division does not exist and is created on the fly at run time. To see the final result as rendered by the browser, you can use a javascript debugger like Firebug. Note the use of the "true" as the last parameter of the vsal_async_get function in place of "false" used in example 5.

EXAMPLE 7 - Using vsal_async_post and vsal_getFormData with an existing DIV:

<html>
<head>
<title>EXAMPLE 7 - Using vsal_async_post and vsal_getFormData with an existing DIV</title>

<script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>
</head>
<body>

<form id="theForm" method="POST" action="" onsubmit="vsal_async_post('http://www.zallocco.net/vsal_test_post.php', vsal_getFormData(this), 'dest', false);return false;">

First name: <input type="text" name="firstname" /><br />
Last name: <input type="text" name="lastname" /><br />
Password: <input type="password" name="pwd" /><br />

<input type="radio" name="sex" value="male" /> Male<br />
<input type="radio" name="sex" value="female" /> Female<br />
I have a bike: <input type="checkbox" name="vehicle_Bike" value="Bike" /><br />

I have a car: <input type="checkbox" name="vehicle_Car" value="Car" /><br />
I like: <select name="music">
<option value="ROCK" selected>Rock</option>

<option value="POP" >Pop</option>
<option value="JAZZ" >Jazz</option>
</select><br/>
<input type="submit" value="Submit" />
</form>

<div id="dest">Please click on button to make me change!</div>
</body>
</html>

What can I say? Simple no? Note the use of vsal_getFormData with parameter "this" that in the scope where was used is equivalent to document.getElementById("theForm") or in same cases to "theForm" but the use of this last form is deprecated by the W3C !!! The POST method solves (in part) the problem of the number of characters usable on the URL (see note above).

EXAMPLE 8 - Using vsal_sync_get and vsal_sync_post:

<html>
<head>
<title>EXAMPLE 8 - Using vsal_sync_get</title>
<script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>

</head>
<body>
1)<br />
<div id="dest1">If all goes well, this text should change after the first image is loaded.</div><br />
2)<br />

<img src="http://www.zallocco.net/vsal_example/testimage1.jpg" /><br />
3)<br />
<div id="dest2">If all goes well, this text should change after the middle and top image are been loaded.</div>

<script type="text/javascript">
 alert("Please close me!!");
 document.getElementById("dest1").innerHTML = vsal_sync_get('http://www.zallocco.net/vsal_example/sometext.txt','');
 alert("Please close me!!");
 
document.getElementById("dest2").innerHTML = vsal_sync_post('http://www.zallocco.net/vsal_example/sometext.txt','');
</script>
</body>
</html>

As you can see we load at run time a TXT file with inside a piece of HTML code, but of course you can load any text-based file or PHP script response. The main difference between the syncronous and asyncronous method is that execution of script will be interrupted until the remote content was loaded. This function is usefull, for example, to load the content of the various divisions in a predefined order. Imagine you have an HTML template, with various divisions defined for menu, header, footer and body and that you will load it in a predefined sequence: heder first, then menu, body and finally the footer, so the syncronous functions is what you need! As mentioned above, the only difference between GET and POST methods resides in the maximum number of characters that can be handled!

EXAMPLE 9 - Using vsal_load_xml:

<html>
<head>
<title>EXAMPLE 9 - Using vsal_load_xml</title>
<script src="http://www.zallocco.net/vsal.js" type="text/javascript"></script>

<script type="text/javascript">
 var xmlDoc = vsal_load_xml("http://www.zallocco.net/vsal_example/data.xml","");
 var x = xmlDoc.getElementsByTagName("CD");
 var i=0;

 
function displayCD() {
 var artist = (x[i].getElementsByTagName("ARTIST")[0].childNodes[0].nodeValue);
 var title  = (x[i].getElementsByTagName("TITLE")[0].childNodes[0].nodeValue);
 
var year   = (x[i].getElementsByTagName("YEAR")[0].childNodes[0].nodeValue);
 var txt    = "Artist: " + artist + "<br />Title: " + title + "<br />Year: "+ year;
 
document.getElementById("showCD").innerHTML = txt;
 }

 function next() {
 if (i < x.length-1) {
 i++;
 displayCD();
 }
 }

 function previous() {
 if (i > 0) {

i--;
 displayCD();
 }
 }

</script>
</head>
<body onload="displayCD()">

<div id='showCD'></div><br />

<input type="button" onclick="previous()" value="<<" />
<input type="button" onclick="next()" value=">>" />

</body>
</html>

This example has been taken from W3Schools and modified to work with vsal.

Download:

Download the library: But I will suggest to link the library directly from my site to have it always updated!

Last Update: 12/12/2014 13:11:55.

Menu

News:

Select Language:

VSAL: The Very Simple Ajax Library

Going into details:

Importing the library:

Usage Example:

Download: