Trevweb

In this third and (as seems most likely at the moment) final article about developing a JavaScript ‘include’ facility, I’ll address the provision of ‘include-once’ functionality. If you’ve not read the previous two articles, or you wish to refresh your memory, my first JavaScript ‘include’ article discussed the basic need for an ‘include’ feature, and offered a reasonable first stab at an implementation. It also outlined two key shortcomings of this first attempt. The first shortcoming, the proper handling of relative paths to included files, is dealt with in my second JavaScript ‘include’ article; the second issue of how to deal with the same files being included more than once, is presented here.

Disclaimer

Please see my JavaScript disclaimer in the first JavaScript ‘include’ article. It still applies, and constructive comments are welcome on any gaffes or oversights.

What Is Include-Once?

In addition to an include facility, many languages offer the ability to be able to ‘include-once’. Where source files are variously dependent upon other files and upon each other, it’s easy to see how the same files could be included over and over. Being able to include-once would prevent such multiple inclusions of the same file by automatically only including each file the first time it’s included.

From the caller’s point of view, using include-once is syntactically very similar to using a regular include, e.g.:

includeOnce("usefulLib.js");
usefulFn();

In this example, the ‘usefulLib.js’ file (which presumably includes the implementation of the ‘usefulFn()’ function) would only be included if it hadn’t previously been included before (irrespective of whether the previous inclusion was performed using ‘include()’ or ‘includeOnce()’).

Even with ‘includeOnce()’ available, it would still be possible to force an include to take place. In the following code snippet, both ‘someCode1.js’ and ‘someCode2.js’ would be included twice:

include("someCode1.js");
include("someCode1.js");

includeOnce("someCode2.js");
include("someCode2.js"); // Only 'includeOnce()' checks for previous inclusion.

Although for most purposes (or so it seems to me), ‘includeOnce()’ would be more useful than ‘include()’, a regular non-exclusive inclusion may still have its place. For example, you may want to include a chunk of JavaScript that generates dynamic page content in situ (using ‘document.write()’, say). If you want this dynamic content to appear more than once in the page, then it may be necessary to force the multiple inclusion of such code snippets. Ideally, then, both ‘include()’ and ‘includeOnce()’ would be available.

Implementing Include-Once

In order for the ‘include’ facility to be able to establish whether a file has previously been included, we need some means to uniquely identify files. Clearly, filename alone isn’t sufficient because different files could have the same filenames (as long as they’re within different directories). Although it might be tricky to think of a circumstance where a developer would have such an arrangement, it is possible in principle, therefore we need to make sure our ‘include-once’ feature won’t be wrong-footed by it.

Perhaps what we need is to use full pathnames (or even full URLs) to identify files. In [part 2 of this article series], better handling of file pathnames was introduced, but relative paths alone won’t cut it. If, for example, two files in different directories both include the same third file, they could refer to it using relative paths that won’t necessarily match exactly. In other words, although we’d have the same file being included twice, a casual glance at the relative paths alone might lead us to believe that two different files are being included.

Whenever an ‘include()’ or an ‘includeOnce()’ is requested, then, we’ll need to do a fair bit of processing on the supplied pathname to establish the full URL of the included file.

There are two parts to this process. Firstly, we need to take a look at the include file path we’ve been given and prefix it with whatever is required to make it into a full, absolute URL. At one extreme, this could involve no modification (in the case where we were supplied with a full URL anyway); at the other, we could be adding everything but the filename. Secondly, we need to make sure that the full URL we have doesn’t contain any ‘.’ or ‘..’ (i.e., ‘this directory’ or ‘parent directory’) parts, because this too could make two references to the same file look different from each other.

Although the process of converting (what could be) a relative include path into a full, absolute URL isn’t the proverbial rocket science, it is still a bit fiddly, and, requires more lines of code than it feels it deserves. I’ve implemented the process via two functions: ‘getRealUrl()’ that takes a full URL (i.e., one that begins with ‘http://’ and includes a domain) and parses out the ‘.’ and ‘..’; and ‘getAlreadyIncludedKey()’ that makes sure the include path is a full URL before calling upon ‘getRealUrl()’ to make sure there are no ‘.’ and ‘..’ parts.

So, ‘getAlreadyIncludedKey()’ provides us with a unique reference to a file to be included, thus giving us a means to recognise whether we’ve been asked to include a supplied file before. As the function’s name suggests, we can then use this reference as a key into a JavaScript object, for which I’ll use a global variable called ‘_alreadyIncluded’.

Using a file’s full URL as a key, we can then make a note of every file that’s included (using either ‘include()’ or ‘includeOnce()’) and automatically refrain from including it as necessary if it has been included before (using ‘includeOnce()’).

The Final Include Code in Full

It’s taken quite an effort to produce as comprehensive an ‘include’ facility as a modern language ought to offer, but here’s the full implementation in all its glory (I toyed with the idea of only including in full those extra bits required for ‘include-once’ support, but thought it would be more convenient to work with if anyone was actually tempted to try using this new facility):

var _includePath = "";
var _alreadyIncluded = {};

// Essentially 'new XMLHttpRequest()' but safer.
function newXmlHttpRequestObject()
{
    try
    {
        if (window.XMLHttpRequest)
        {
            return new XMLHttpRequest();
        }
        // Ancient version of IE (5 or 6)?
        else if (window.ActiveXObject)
        {
            return new ActiveXObject("Microsoft.XMLHTTP");
        }

        throw new Error("XMLHttpRequest or equivalent not available");
    }
    catch (e)
    {
        throw e;
    }
}

// Synchronous file read. Should be avoided for remote URLs.
function getUrlContentsSynch(url)
{
    try
    {
        var xmlHttpReq = newXmlHttpRequestObject();
        xmlHttpReq.open("GET", url, false); // 'false': synchronous.
        xmlHttpReq.send(null);

        if (xmlHttpReq.status == 200)
        {
            return xmlHttpReq.responseText;
        }

        throw new Error("Failed to get URL contents");
    }
    catch (e)
    {
        throw e;
    }
}

function include(filePath)
{
    includeMain(filePath, false);
}

function includeOnce(filePath)
{
    includeMain(filePath, true);
}

function includeMain(filePath, once)
{
    // Keep a safe copy of the current include path.
    var includePathPrevious = _includePath;

    if (isAbsolutePath(filePath) == true)
    {
        var actualPath = filePath;
        // Absolute paths replace.
        _includePath = getAllButFilename(filePath);
    }
    else
    {
        var actualPath = _includePath + filePath;
        // Relative paths combine.
        _includePath += getAllButFilename(filePath);
    }

    var alreadyIncludedKey = getAlreadyIncludedKey(actualPath);

    if (once == false || _alreadyIncluded.alreadyIncludedKey == undefined)
    {
        var headElement = document.getElementsByTagName("head")[0];
        var newScriptElement = document.createElement("script");

        newScriptElement.type = "text/javascript";
        newScriptElement.text = getUrlContentsSynch(actualPath);
        headElement.appendChild(newScriptElement);
        _alreadyIncluded.alreadyIncludedKey = true;
    }

    // Restore the include path safe copy.
    _includePath = includePathPrevious;
}

function isAbsolutePath(filePath)
{
    if (filePath.substr(0, 1) == "/" || filePath.substr(0, 7) == "http://")
    {
        return true;
    }

    return false;
}

// Strips the filename from a path, yielding everything else.
function getAllButFilename(filePath)
{
    return filePath.substr(0, filePath.lastIndexOf("/") + 1);
}

// Yields a full, real URL to be used as a file's include key.
function getAlreadyIncludedKey(filePath)
{
    if (filePath.substr(0, 7) == "http://") // Full URL?
    {
        return getRealUrl(filePath);
    }

    if (filePath.substr(0, 1) == "/") // Absolute path?
    {
        return getRealUrl("http://" + document.domain + filePath);
    }

    // Otherwise, assume relative path.
    return getRealUrl("http://" + document.domain +
        getAllButFilename(document.location.pathname) + filePath);
}

// Takes a file path as a 'full' URL (including 'http://' and domain) and
// yields a 'real' version of it with no '.' and '..' parts.
function getRealUrl(fullUrl)
{
    var protocolAndDomain = fullUrl.substr(0, fullUrl.indexOf("/", 7));
    var urlPath = fullUrl.substr(protocolAndDomain.length + 1);
    var urlPathParts = urlPath.split("/");
    var realPath = "";
    var parentCount = 0;

    for (var i = urlPathParts.length - 2; i >= 0; i--)
    {
        if (urlPathParts[i] == ".")
        {
            continue;
        }

        if (urlPathParts[i] == "..")
        {
            parentCount++;
            continue;
        }

        if (parentCount > 0)
        {
            parentCount--;
            continue;
        }

        realPath = urlPathParts[i] + "/" + realPath;
    }

    return protocolAndDomain + "/" + realPath +
        urlPathParts[urlPathParts.length - 1];
}

Conclusion

My own feeling about the final implementation is that it seems like an awful lot of code for adding a ‘mere’ include feature to a language, even if it is one that seems to be fairly comprehensive. I could have made the code shorter, of course, but only at the expense of making it either flakier or less flexible and powerful (unless we’re talking about just removing all unnecessary whitespace). If you’re prepared to put up with the limitations of the code presented in the first article, for example, then clearly it could be shorter, but only the fuller version presented here offers anything like the equivalent feature available in other languages.

Only time will tell whether I make use of my own new facility (and, in any event, it will need further testing and/or use before I’ll be satisfied that it is fully reliable with no lingering bugs), but at the very least, I’ve found that the journey has been interesting, and there are a few useful little functions and code snippets that, quite apart from forming part of the final ‘include’ implementation, may be useful in their own right. I can imagine, for example, that the algorithm used by the ‘getRealUrl()’ function for parsing the ‘.’ and ‘..’ bits from pathnames may in itself turn out to be useful one of these days.

Anyway, as ever, I’m open to your constructive comments and thoughts. And thanks for reading.