Going into details:But not too much!
Now we'll take a look at the four groups of functions:
- 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.
- 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";
- 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.
Usage Example:Now we present some example on how to use the various function:
EXAMPLE 1 - Using vsal_get_url_vars:
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:
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:
This is a very simple functions that don't need too many explainations!
EXAMPLE 4 - Using vsal_async_get_alert:
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:
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:
EXAMPLE 7 - Using vsal_async_post and vsal_getFormData with an existing DIV:
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:
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:
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!