Documentation

Features

• network requests using the post or get method
• wrapper function around two (or potentially more) methods
• return format is ready to use XML node or text/json format
• network requests can be repeatedly called on the same request object
• callback function can be either a function or an object

Dependencies on external files and functions

1. helper_functions.js:
   • all the global variables at the top of the file
   • object getData, including all its (prototype) methods

Step by Step Instructions

Step 1: Download and link the file helper_functions.js in your svg file

Download the helper_functions.js and place it in the same directory where your svg file resides in (or adopt pathes as appropriate). Link the javascript file using the following syntax:

	<script type="text/ecmascript" xlink:href="helper_functions.js" />

Step 2: Create an instance of the getData object

The following code creates an instance of the getData object. Place this code in the appropriate position of your javascript function or object. The following example uses the get method.

var getDataObj = new getData(url,callBackFunction,returnFormat,method,postText);

Constructor of the getData object in order of the parameters to be passed over:

• url (string): the URL or the network resource to call (can be a static file or a serverside script)
• callBackFunction (function or object instance): name of a function or object instance. In case of an object instance the method .receiveData() is called.
• returnFormat (string, either 'xml' or 'json'): in case of xml a DOM XML node containing the data received by the server is passed to the callback function. This went already through parseXML() or document.importNode() depending on the available methods. In case of "json" a plain text is passed to the callback function containing the answer received from the URL/server resource.
• method (string, either 'get' or 'post'): specifieds whether getURL or postURL, resp. the get or post method of the XMLHttpRequest() object is used. The get method encodes the information in the URL specified and is thus useful for smaller amounts of information. The post method transfers information of any length, which is not visible in the URL.
• postText (string or undefined): the string containing the information to be transfered by the post method. In case of the get method, you can pass undefined.

Useful Properties of the getData Object

• .url:
  holds the URL of the resource to be queried by the network request. In the case of a repeated get request this URL probably has to be changed.
• .postText:
  holds the information of the text transfered with the post method. Before repeated post requests, this information probably has to be changed.
• .callBackFunction:
  holds the callback function or object instance that is called upon receiving the data

Examples:

var getDataObj = new getData("myWeatherData.xml",parseWeatherData,"xml","get",undefined,undefined);

//preparing the get request
var currentYGet = 80;
var baseUrlGet = "senddatetime.php?currentY=";
var getDataObj = new getData(baseUrlGet,receiveData,"xml","get",undefined,undefined);

//preparing the post request
var currentYPost = 80;
var postDataObj = new getData("sendBackClientTime.php",receiveData,"xml","post","",undefined);

The second and third example are preparing the get and post requests in our example file. Note that creating the object instance does not yet trigger the network request.

Step 3: Triggering the .getData() method of the getData object

When creating the instance of the getData object, the network request is not immediately made, until the .getData() method is called. The idea being that the same object instance can be used to repeatedly trigger network requests, potentially changing URL get parameters or the .postText property in between. The following 2 examples trigger the get and post requests in our example:

//calling the method .getData() of the getDataObj instance
//this is triggered by the click event on the left text element
currentYGet+=20;
getDataObj.url=baseUrlGet+currentYGet;
getDataObj.getData();

//calling the method .getData() of the getDataObj instance
//this is triggered by the click event on the left text element
currentYPost+=20;
var curDateTime=new Date();
postDataObj.postText=currentYPost+'$'+curDateTime.toGMTString();
postDataObj.getData();

Note that currentYPost and currentYGet are increased by twenty units each time the network request is made. This information is passed to the PHP script (server) and used for creating the response.

Step 4: Create the resource to be requested (often a dynamic serverside script or application)

In the simplest case the resource to be loaded with the getData network request is a static XML or text file. Often, it is a serverside scriping application or CGI program. Below is a simple PHP code (of our example) processing the get request:

<?php
header('Content-type: text/xml');
$currentY = $_GET['currentY'];
print '<g xmlns="https://www.w3.org/2000/svg">'."\n";
print "\t".'<text x="10" y="'.$currentY.'" font-size="15">'.date("M d Y H:i:s",time()).'</text>';
print "</g>\n";
?>

This code reads currentY from the get request and then sends a SVG snippet back containing a text element with the current date of the server and the currentY value for the text value (which is increasing whith each request). Also not the text/xml content type and the use of the SVG namespace, which is required that the client correctly determines the namespace of the XML fragment received. In case of a SVG <g/> (group) element or other grouping structure, only the parent element needs to include the SVG namespace. The following PHP code processes a post request:

<?php
header('Content-type: text/xml');
list($currentY,$clientDate) = explode("$",$HTTP_RAW_POST_DATA);
print '<g xmlns="https://www.w3.org/2000/svg">'."\n";
print "\t".'<text x="500" y="'.$currentY.'" font-size="15">'.$clientDate.'</text>'."\n";
print "</g>\n";
?>

Compared to the get request, the whole post textstring resides in one variable, not every parameter separately, as with the get variables.

Step 5: Create the callBack function

Finally, we need to create the callBack functions which are triggered when the web browser receives the data he requested from the resource. In our example we requested XML data chunks in both cases. This means that our callBack functions receive ready to use XML nodes. Because the PHP scripts return a chunk of SVG (text elements) we can directly use these SVG elements and add them to the DOM tree of the SVG document. This is done by the following callback function found in index.svg:

function receiveData(node) {
	document.documentElement.appendChild(node);
}

In this case we receive the SVG <text/> element and append it in the root element of the document, which means at the end of the file.

Discussion

Note that the XMLHttpRequest() can do much more besides requesting data with the get and post method. As an example, one could monitor download progress for larger resources that are loaded, using the progress event. Additionally, one could create, rename, move and delete resources on a web server, assuming that the web user has the permissions to do so. See the www.w3.org/TR/XMLHttpRequest/ W3C XMLHttpRequest() specification for a full list of options.

It is also important to know that for security reasons, network requests (at least in the case of getURL/postURL) are restricted to the same resource where the currently loaded SVG files came from. One cannot load the SVG file from server A and then do network requests to server B. If one needs data from server B, server A has to act as a proxy server and request the data from server B and forward it to the client.

Other Resources:

• www.w3.org/TR/XMLHttpRequest The W3C XMLHttpRequest() specification
• en.wikipedia.org/wiki/XMLHttpRequest The XMLHttpRequest page at Wikipedia

Version history

• 1.0 (2007-02-23): initial version
• 1.1 (2007-05-01): added this.additionalParams, added jsDoc comments
• 1.2 (2011-10-01): added compatibility for IE9 and above - thanks to hints from Bruce Rindahl

Credits

• Bruce Rindahl for pointing me to the fix to add compatibility with IE9 and above.