Dynamic Script Request API

Last Modified: 2005-12-30 (change history)

Problem

How to use On-Demand JavaScript (dynamically creating a SCRIPT tag and attaching to the HEAD) for loading new data or UI, but get the following limitations:
  • Knowing when script load is complete.
  • GET URL length restrictions.
If there is a solution to these limitations, then it opens up accessing data and UI from other domains, something XMLHTTPRequest cannot do.

Knowing when script load is complete.

There is no reliable way to know when the script load is complete. The onreadystatechange event handler is not consistent in its behavior within and across browsers. The API described in this document introduces URL parameters as part of the URL query string to specify JavaScript functions that should be called at the end of the dynamically script files.

GET URL length restrictions

URLs have length restrictions. It differs between browsers, browser versions and web servers, but around 1KB seems to be a safe limit to use for URLs This can be problematic if you need to send larger amounts of data back to the server. This API uses multipart script requests to segment the original server request into manageable chunks. There are URL parameters in the query string that specify what part is being sent, and what JavaScript function the dynamically added script file should call once that part is processed.

Prerequisites

API Description

URL Parameters

Here is the list of URL querystring parameters that will be on the URL to support communicating when the script has finished loading, and to support multipart requests. Underscores are used on the parameter names to help avoid conflict with the application/web site's parameters.

_id
A unique ID to identify the full request, if it is a multipart request. Sent with every multipart request. ID may only be unique to within a web page instance. The server should be careful about multiple open pages and/or users sending the same ID.

_error
The name of a JavaScript function the server can call if there was an error. Optional. If this parameter is not sent, then the server can return a response that throws a JavaScript exception.

_ok
The name of a JavaScript function the server calls when all parts are received and processed and the server has generated a successful response. In a multipart request, this parameter is only sent with the last part, indicating that there are no more parts. The JavaScript data for the response should be passed as the first parameter to this function.

_part
The current part number, if it is a multipart request.

_partOk
The name of a JavaScript function the server calls when it successfully processes this part of the request. Only sent in multipart requests. It will be sent with every part of the request, except the last part (which will have the _ok parameter instead). The successfully processed part number should be passed as the first parameter to this function. Updates to the constant URL parameters (if any) should be the second argument. Constant URL parameters are parameters required by a particular URL that should be sent with every request in a multipart request. An example of this would be a session ID or server-generated request ID.

Example URL

http://somedomain.com/serverpath?_ok=requestComplete&_error=requestError&target=foo&color=blue

The page that adds this URL to a script element would have the following JavaScript functions:
function requestComplete(data)
 {
 alert('Changing of color is complete. The new color is ' + data.finalColor);
 }

function requestError(error)
 {
 alert('Error processing request: ' + error);
 }
Here is an example JavaScript server response for the successful case:
requestComplete({ name: foo, finalColor: 'blue' });

Example Multipart URL

Building on the first example, say there is a third parameter bar=ThisIsAReallyLongValue (where that value *is* very long, over the 1 KB limit). The set of script URLs would be:
http://somedomain.com/serverpath?_id=id1&_part=1_partOk=partComplete&_error=requestError&target=foo&color=blue&bar=ThisIsARe
http://somedomain.com/serverpath?_id=id1&_part=2_ok=requestComplete&_error=requestError&target=foo&color=blue&bar=allyLongValue
In addition to the requestComplete and requestError functions described in the first example, the page would also have this method defined:
function partComplete(part, constantParams)
 {
 //Increment part, then add the second URL via dynamic script add, 
 //passing any constantParams in the next URL.
 }
Example JavaScript server responses for each URL:

Part 1:
partComplete(1, null); //This example does not have any constantParams.
Part2:
requestComplete({ name: foo, finalColor: 'blue' });

Data Segmentation in Multipart URLs

The Multipart URL example showed that some of the URL parameters might get segmented across requests, and it might get segmented
in the middle of the value of a name=value pair. If that is the case, the next request will contain the next segment of the value, with the name= in front of it.

So, for the above example:
bar=ThisIsAReallyLongValue
was segmented like this:
bar=ThisIsARe
bar=allyLongValue
Any of the "constant parameters" that the server needs will never be segmented.

Tagneto Implementation

Tagneto support this API via the Dsr.send() method defined in Dsr.js. send will add all of the above parameters, and will segment the URL into a multipart URL if it is bigger than 1KB.

Outstanding implementation issues:
  • This method does account for fragment identifiers (#identifier on an URL). Don't use it if you have fragment identifiers. If there is a great enough need for fragment identifier support, then it might be added later.
  • The method does not take into the account on whether the URL that is given to it is a relative or absolute URL. Additional space allowance may be necessary if it is a relative URL. More investigation is needed.

Open Issues


Change History

2005-12-30: Made _error optional. If not sent, server can throw a JavaScript exception for the response. Changed SvrScript references to Dsr references.
2005-11-22: Initial version.
Copyright © 2005 tagnetic.org.