The DIV_SRC Tool

How to Invoke DIV_SRC – the Details

DIV_SRC scans a nominated HTML document in part or in whole as directed, looking for references to other file fragments. It uses AJAX to asynchronously fetch the file fragments that a page refers to. As each fragment arrives it is injected into the tag that referenced it, replacing that tag's prior content, if any. At your option, DIV_SRC.resolve() will scan the content that it fetches for further injection opportunities. If for example the content that is fetched for <div src="one.html"></div> contains this reference: <div src="two.html"></div> then DIV_SRC can fetch and inject the two.html document fragment as well. The depth to which this recursive resolution takes place is controlled by a depth parameter.

Invoking DIV_SRC from <body onLoad>

The simplest way to get DIV_SRC to inject the files that you have removed from your page is to include the onLoad="DIV_SRC.resolve()" parameter in the page's <body> tag, but you can allow the user to trigger the fetching of referenced page section at any time, by clicking on a form widget that has the attribute onClick="DIV_SRC.resolve()" for example.

Content injection can be requested for tag types other than <div>. Tags such as <span>, <td> and <p> are other potential targets. You can specify which tag types you want DIV_SRC.resolve() to process in the parameters that you pass to it. <img> is not a good candidate!

DIV_SRC is packaged as a JavaScript object to minimise intrusion on the caller's name space. A single JavaScript variable name, DIV_SRC, is set. Within this object, the method name DIV_SRC.resolve() is made visible.

DIV_SRC.resolve() exits with a return code of 0 if successful, or 1 if an error prevents its execution.

Bimodal Web Pages

Some browsers, especially those that run on mobiles, do not support AJAX. Content providers may wish to build bimodal page segments that can either be fetched and imbedded in a large composite page by AJAX-capable browsers, or displayed as separate small pages by browsers that don't implement AJAX. DIV_SRC has facilities that allow content providers to structure page segments with all of the normal HTML tags that are required in stand-alone web pages, and to have these spurious HTML tags stripped out of the page segments when they are loaded into a base page by a browser that implements AJAX. This approach is described in more detail in the Problems section.

DIV_SRC.resolve() Parameters

The DIV_SRC.resolve() method accepts various parameters, thus: DIV_SRC.resolve(parameters). All of the parameters are optional. If supplied, parameters must be coded as a JavaScript object enclosed in {braces}. It must contain keywords followed by values. Keywords are separated from values by colons (:). If there is more than one keyword-value pair, separate them with commas. For example: DIV_SRC.resolve({depth: 2, debug: 1})

The available parameters appear below:

debug
if debug:null or this parameter is absent, no debug information is published.
if debug:1, a colored border is set on each HTML element that has content injected into it; the tag that triggered the injection is set as a title (tooltip) for the injected content and appears when the mouse hovers over it.
debug:2 gives the same as debug:1, plus the HTTP response headers for each section of content returned. Note that if the request status code is 304 (content found in cache), XMLHttpRequest() may report this as status code 200 (content successfully retrieved from the source web server), probably to make things simpler for programmers. Use a tool like
Live HTTP Headers if you want to see what's really going on.
depth
is a positive integer that specifies how deeply DIV_SRC should recursively resolve the <div src="URL"> nodes that it injects. The default is 5. This parameter helps to limit damage done by circular content references, e.g. <div src="a.html"> includes <div src="b.html"> includes <div src="a.html">. The code does check for circular references and should refuse to refetch a section that has itself as a parent, but these checks will fail if the query portion of the URI varies.
dropSRC
if dropSRC: true is passed then the src="URI" attributes of the tags operated on will be removed after their content has been replaced. This is a debug option to help generate legal HTML that can be checked with various HTML syntax checkers.
warning: if this parameter is supplied then DIV_SRC will not detect circular references; eliminate these before setting this parameter.
lang
the two-character ISO language code to use for publishing messages to the browser user. Default is "en" (English).
loadMsg
either a string to be displayed in each selected <div src="URI"> section while its new content is being fetched; or true, in which case the default loading message will be displayed in each; or false (equivalent to not passing this parameter), in which case the content of the selected <div src="URI"> sections will not be not overwritten while their new content is being fetched. If the loading message string includes a @ character, it will be replaced by the matching URI; if you want to display a @ character and not have it changed to a URI, use the &#64; HTML entity instead like this: @. If any requested segment fails to arrive then the loading message will remain displayed indefinitely. The loading message may include a URL and instructions to the user to click it if loading does not complete. You probably won't want to pass this parameter if you are building bimodal pages.
noAJAX
if noAJAX: true is passed then DIV_SRC.resolve() will act as if the browser does not implement AJAX. This can be used to test how a given page would be handled by a browser that has no AJAX support in one that has. If noAJAX: "message" is passed the message string will be displayed to browser users if their browsers don't support AJAX. If the string has length zero then it isn't displayed, but DIV_SRC exits silently with a return code of 1, signalling the absence of AJAX support. If the string has length > 0 then it will replace the entire page. It can contain HTML markup, and could for example carry a hyperlink to the composite page fully assembled, so that composite pages can still be viewed through browsers without AJAX support. You could even include a <META HTTP-EQUIV=Refresh> tag that would automatically take the browser to the full composite page after a short delay. See the Problems page for suggestions on how this parameter can be used to help handle browsers that don't implement AJAX.
onerror
if you wish to handle any errors that may occur when remote files are fetched by AJAX calls, then supply the name of a JavaScript function that will receive control as each such error occurs. It will be passed the arguments(node, uri, text):
node is the DOM node that referenced the remote content, e.g. <div src="URI">
uri is the uri of the content that could not be fetched, e.g. <div src="URI">
text is an error message string
Bear in mind that your error handling function may be invoked more than once. Do not write parentheses after the function's name, that will cause it to be invoked immediately. For example, DIV_SRC.resolve({onerror: handleError}), or DIV_SRC.resolve({onerror: function(node,uri,text) {alert("Error "+text+" for URI " + uri)}})
strip
if strip: true is passed then DIV_SRC.resolve() will transform the page segments that it fetches using AJAX and embeds into the base page. It will strip out the HTML wrappers that are required by a stand-alone web page, but that are inappropriate in a page segment that is embedded into a base page. These include the <!doctype>, <html> and </html> tags, <body> and </body> tags, and all content between and including the <head> and </head> tags. It is appropriate to use this parameter when the page segments are bimodal, that is to say, intended to be displayed as stand-alone pages by browsers that don't implement AJAX, but to be embedded within a base page by browsers that do support AJAX.
tags
is an optional array of strings that identify the tag types to be processed. This defaults to tags: ["div"]. Other tag types may be specified, e.g. tags: ["div","span", "td"] would process <div src="...">, <span src="...">, and <td src="..."> tags. If an empty array of tags is passed thus: tags: [] then DIV_SRC.resolve() exits normally without changing the page at all. This form can be used to assist with debugging.
target
is the DOM node to be scanned for tags like <div src="URI">; this node and its children will be inspected, and if candidate tags are found, their content will be replaced by fresh content fetched from the web server. You can specify any DOM node that JavaScript can access, such as window, document, or window.parent.frames["fr1"]. Target may refer to a different window if its page comes from the same domain, e.g. window.opener. Alternatively, as a convenience, you can specify the target as a document ID in a string – DIV_SRC.resolve({target: "myID"}) is equivalent to DIV_SRC.resolve({target: document.getElementById("myID")}). If target is not supplied then the current document.body is taken as the default target.

DIV_SRC URIs

The URIs referenced by <div src="URI"> or similar tags must follow the same pattern as a URI in an <img src="URI">. They can be:


© Trevor Turton, http://turton.co.za, 2008-10-12