Script execution and modules

The main script

The script you give to SlimerJS is a javascript script.

The script is considered by SlimerJS as a module. SlimerJS uses a modified version of the module system of the Mozilla Addons SDK. It implements the CommonJS module specification version 1.1.1

The script has access only to few objects in its context (see below). Modules define other objects. Some are provided by SlimerJS, but you’ll certainly provide your owns modules.

So to execute something, to use some APIs, most of time you’ll have to import modules into your script, with require().

Another way to use objects of an other script, is to inject it into your script.

Modules

A module is a javascript file that defines functions to export and has an id. The id of modules you provide and use, is the name of the module file in the current working directory, without the ‘.js’ extension.

Some internal module have a specific id. The script given to SlimerJS is the module “main”.

To define functions and variables to export, the module should store these functions and variables into an exports object

exports.printHello = function(param) {
    console.log('hello '+param)
}

exports.aValue = 123

exports.otherFunction = function() {  }

If the module is stored into a hello.js file in the same directory of the main script, in the main script you can use the module like this:

// import functions into an object
var hello = require('hello');

// call the exported function
hello.printHello('Bob');

By default, you can only load modules that are stored in the directory of the main script (and in its sub-directories). The id you give to the require function is always resolved from this directory, except if you indicate an id starting with ”./”: it is resolved from the id of the current module.

If you want to load modules from other directories, you can indicate their path into the array require.paths

var path = fs.absolute(phantom.libraryPath + '/../vendor-modules/');
require.paths.push(path);

Modules and main script context

Each module is executed in its own sandbox. It means that it cannot access to variables or objects defined outside the module.

In fact, to mimmic PhantomJS, the main script is executed in the context of a blank page (about:blank). So it has access to a window object and a document object. These objects are in fact injected into the module sandbox. And these objects are shared with other modules.

In their sandbox, modules and the main script have access to other native objects and functions:

  • require() to import modules
  • module, an object that have information about the module itself
  • phantom which is an object similar to the object phantom you have in PhantomJS.
  • slimer which is an object that provides some “utils” functions

Warning: unlike PhantomJS, these functions and objects are not properties of the window object.

Of course, you have access to other Javascript native objects like Date, RegExp, Math, console...

Injecting scripts

If you want to include a script (that is not a module), into a module, you have to use phantom.injectJs(aFileName). Remember, the main script is considered as a module.

The indicated path should be relative to the main script directory, or it can be an absolute path of course. You can change the default directory by setting the path of the new directory to phantom.libraryPath.

The injected script is then executed into the context of the current module (into the sandbox of the module), as if it is part of the module. It has then access to all variables and functions defined by the module.

Table Of Contents

Previous topic

Quick Start

Next topic

Configuration

This Page