< documentation

API

options

hooks

platform

options

  • Envjs provides a number of basic configurable options which allow users to modify the default behavior the code base.

    Options, Hooks, and Platform functions are all set, or overridden via the same mechanism, using Envjs as a function whose argument as an object is used to effectively replace the default value.

    Options and Hooks are the end-users API, while Platform is the developers API for providing a bridge to another host language and/or javascript language.

    Of course the nature of Javascript as a language make it easy to extend or replace the Envjs API including the core browser API's like DOM, HTML, XHR, etc. We are also encouraging developer to package their adaptations as simple plugins that can be shared with the community

  • scriptTypes

    Sets the script types that Envjs will load and run as part of the page loading process. Envjs will not load external javascript by default. Please be aware of the security implications before you allow arbitrary scripts to run on your system.

    This can be used to run some scripts in a server environment, or for more general multi-pass treatments of documents.

    Defaults
    type load
    anonymous false
    text/javascript false
    text/envjs true 
    /**
 * this will now load and run all external javascript, 
 * emulating browser behavior
 */
Envjs({
    scriptTypes : {
        '': true, //inline and anonymous
        'text/javascript': true,
        'text/envjs': false
    }
});

window.location = 'http://www.w3c.org/';

  • appCodeName

    Sets the value returned for window.navigator.appCodeName For example, in Firefox this is 'Mozilla'.

    default: 'Envjs' 

    //returns 'Envjs'
window.navigator.appCodeName;

Envjs({
    appCodeName:'Mozilla'
});
//returns 'Mozilla'
window.navigator.appCodeName;

  • appName

    Sets the value returned for window.navigator.appName in Firefox this is 'Netscape' (can be used to emulate different browsers)

    default: 'Netscape' 

    //returns 'Netscape'
window.navigator.appName;

Envjs({
    appName:'MyApp'
});

//returns 'MyApp'
window.navigator.appName;

  • tmpdir

    Sets the directory Envjs will use to write temporary source files for script tags with javascript inline. This is required for the rhino debugger and will likely be deprecated in the future unless explicitly using a debugger.

    This is analogous to the process Firebug uses to provide the ability to see locally 'eval'uated script.

    default: java.lang.System.getProperty('java.io.tmpdir') 

    Envjs({ 
    tmpdir:'/opt/tmp'
});

  • os_name

    Sets value which is returned as part of window.navigator.appVersion In Firefox on OSX this is '5.0 (Macintosh; en-US)'

    default (rhino): java.lang.System.getProperty('os.name') 

    Envjs({
    os_name:'Win 98'
});

  • os_arch

    Sets value which is returned as part of window.navigator.platform In Firefox on OSX this is 'MacIntel'

    default (rhino): java.lang.System.getProperty('os.arch') 

    Envjs({
    os_arch:'Pentium II (386)'
});

  • os_version

    Sets value which is returned as part of window.navigator.userAgent In Firefox on OSX this is 'Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.5; en-US; rv:1.9.1.2) Gecko/20090729 Firefox/3.5.2'

    default (rhino): java.lang.System.getProperty('os.version')

    Envjs({
    os_version:'Intel Mac OS X 10.1'
});

  • lang

    Sets value which is returned as part of window.navigator.userAgent In Firefox on OSX this is en-US

    default (rhino): java.lang.System.getProperty('user.lang')

    Envjs({
    lang:'fr'
});

  • platform

    Sets value which is returned for window.navigator.platform In Firefox on OSX this is MacIntel, for Envjs this should be zet by the providing host language and javascript engine

    default (rhino): 'Rhino'

    Envjs({
    platform:'PyV8'
});

  • javaEnabled

    Sets value which is returned as part of window.navigator.javaEnabled

    In env.rhino.js this is set to true, though we may need to give this some deeper consideration.

    default (rhino): true

    Envjs({
    javaEnabled:false
});

hooks

  • Hooks allow users of Envjs to extend the usual behavior at well known points, or to subscribe to internal events that a browser would not normally expose.

    These are very useful, for example, to allow Envjs users to run existing HTML files unmodified, while still being able to provide additional information to the console, or to store state regarding the HTML applications processes.

  • beforeScriptLoad

    Uses regular expression matches on script src attributes and allows you to specify a function to call before the matching script is loaded.

    Very useful for setting global values that will affect the setting of the script to be loaded next.

    default: none

    Envjs({
    beforeScriptLoad:{
        'urchin': function(scriptNode){
            scriptNode.src = '';
        }
    }
});
//Wont load tracker javascript library!
window.location = 'http://www.envjs.com/';

  • afterScriptLoad

    Uses regular expression matches on script src attributes and allows you to specify a function to call immediately after the matching script is loaded.

    Very useful for modifying the previously loaded script, for example, to attach a logger to a unit testing framework, or hook some data mining up around existing functions.

    default: none

    Envjs({
    afterScriptLoad:{
        'qunit/testrunner': function(scriptNode){
            //hook into qunit.log
            var count = 0;
            QUnit.log = function(result, message){
                Envjs.log('('+(count++)+')['+ 
                    ((!!result)?'PASS':'FAIL')+']'+message);
            };
        }
    }
});
//We'll now get messages from QUnit at the console
window.location = 'jquery/tests/index.html'

  • onScriptLoadError

    Allows the user to define a single handler to be called if a script tag throws an error when being evaluated for the first time.

    This is a global callback, not an event patterns so defining it twice overrides the previous callback.

    default: none

    //we use this here to safely continue running the scripts
//even though we expect certain jsonp script loads to fail
Envjs({
    onScriptLoadError : function(script){
        console.error('failed to load script ' + script.src );    
        ok(false, 'JSONP may have failed to load locally');
        //allow tests to continue without a full network
        start();
    }
});

  • onInterrupt

    Allows the user to define a single handler to be called whenthe Envjs.timer routine is interupted. Note that this is expected in most cases, such as setTimeout, and setInterval, and even for Ajax, so remember onInterupt does not mean an error necessarily occured.

    This is a global callback, not an event patterns so defining it twice overrides the previous callback.

    default: null

    Envjs({
    //allow unanticipated xhr error with no ajax.handleError 
    //callback (eg jQuery.getScript) to exit gracefully
    onInterrupt: function(){
        Envjs.info('thread interupt: continuing test');
        start();
    }
});

  • onExit

    Called just prior to the application unloading

platform

  • Platform functions are required to be implemented by authors who wish to run Envjs on additional javascript engines. Currenlty only rhino is supported though we hope to support additional engines in the future.

    These functions are also available to the Envjs users as utilities, for example, to write out the resulting dom, after manipulation by javascript, to a local file. Also the default implementations may be easily overridden to suit the users particular needs.

  • log

    Allows the platform to define a method to provide standard output. Expects a string argument and returns nothing.

    env.rhino.js provides an implementation that uses the global Rhino print function. Users that prefer a different outputformat or want to write logs to a file can override this function.

    Envjs.log = function(string){
   //do something with the string
   return;
};

  • uri

    This function is used to resolve paths.

    If it is detected that the first argument already contains a protocol, eg file:, http:, or https:, the url is simply returned.

    If the first argument 'path' does not contain a protocol, and a second arg 'base' is detected, the first argument is resolved relative to 'base' and the absolute url is returned.

    If the first argument 'path' does not contain a protocol, and a second arg is not detected, the first argument is resolved relative to the window.location. 

    Envjs.uri = function(path, base){
    //create an absolute url including protocol
    return absoluteUrl;
}

  • loadInlineScript

    This function is used to execute inline javascript file. 

    Envjs.loadInlineScript = function(scriptNode){
   //load and execute the javascript from the node
   return true;//false if error
}

  • loadLocalScript

    This function is used to load and execute both inline and external javascript files. For platforms which intend to support Frames, this function must be implemented to execute the script in correct window proxy scope; It also contains the hooks for Envjs.beforeScriptLoad and Envjs.afterScriptLoad.

    Envjs.loadLocalScript = function(scriptNode){
   //load and execute the javascript from the url
   return true;//false if error
}

  • timer

    This function implements the waiting strategy for functions executed with setTimeout and setInterval.

    It must synchronize the execution of the timed function in the same scope at which setTimeout or setInterval was called.

    Envjs.timer = function(fn, time){
      //creates a timer, checks the callstack and executes timeouts
}

  • runAsync

    This function implements asychronous execution of functions. It is used primarily by the XMLHttpRequest object to make network calls while scripts continue to run.

    Envjs.runAsync = function(fn){
  //creates a thread and executes the specified function
  //in a synchronized wrapper
}

  • loadFrame

    Loads a frame from the given node Should create a new window proxy for the frame document, load allowed scripts etc.

    Envjs.loadFrame = function(frameNode, url){
    //load frame
}

  • proxy

    Creates a window object with parent windows Probably the most difficult api point in Envjs, this is responsible for creating the Window Proxy object. 

    Envjs.proxy = function(scope, parent){
   //make scope into window proxy with reference to parent
}

  • writeToFile

    Writes text to a file. Used by the XMLHttpRequest when data is PUT to a local file. Useful to write resulting dom to a file after running dhtml on a document. 

    Envjs.writeToFile = function(text, url){
    //dumps the text to the specified url (should be a local file path)
}

  • writeToTempFile

    Writes text to a temporary file. The suffix parameter allows identification of the temporary files writen by Envjs.

    Used prior to executing scripts embedded in html files so they can be traced by debuggers.

    Envjs attempts to delete these files on exit.

    Envjs.writeToTmpFile = function(text,suffix){
      //dumps the text to a temporary file
}

  • connection

    Implements the details of making the connections for XMLHttpRequest

    Envjs.connection = function(xhr, responseHandler, data){
  //makes a connection, posting or url encoding data, 
  //and finally calling the response handler
}

  • deleteFile

    Deletes the file at the given url. Used by XMLHttpRequest when a DELETE is called on a local file.

    javascript
Envjs.deleteFile = function(url){
  //deletes the file at the given url
}