phantomjs-extensions

A set of extensions, shims, utilities, and alternate APIs for PhantomJS. All of these modules run best on PhantomJS 1.7+ with its enhanced require functionality, otherwise you must use an equivalent shim implementation for require.

PhantomConsole

PhantomConsole is a CommonJS module to provide implementations for the console object's methods, most of which are currently missing (as of PhantomJS 1.7.0). PhantomConsole also provides verbosity level filtering, so you can control the amount of data that your console is logging.

Compatibility:

Minimum: PhantomJS 1.2+

Attachment Target: None required, though the intent it to use it to override window.console in the PhantomJS outer space. Don't worry, you can always get the original console implementation back, too (details below).

Basic Usage:

(function(window) {
	var PhantomConsole = require("PhantomConsole"),
		phantomConsole = PhantomConsole.create(PhantomConsole.Verbosity.ALL);
	
	// Override the main `window.console` in the PhantomJS outer space
	console = phantomConsole;
	
	// Use previously unimplemented console methods...
	console.time("Tracing");
	console.trace();
	console.timeEnd("Tracing");
	
	// Revert the main `window.console` in the PhantomJS outer space to its original implementation
	console = PhantomConsole.getOriginal();
	
	phantom.exit();
})(this);

EventEmitter

EventEmitter is a CommonJS module inspired by TJ Holowaychuk's (@visionmedia) emitter component. It provides an API identical to that of the emitter component other than the expected arguments. Most importantly, EventEmitter is a required dependency for BetterWebPage!

Compatibility:

Minimum: PhantomJS 1.2+

Attachment Target: N/A

Basic Usage:

(function(window) {
	var EventEmitter = require("EventEmitter"),
		emitter = new EventEmitter();

	// Can accept a function callback
	emitter.on("ready", function(time) {
		console.log("Ready! At: " + time);
	});

	// Can accept a structured object
	emitter.on("ready", {
		/* The function callback that you can also pass in on its own */
		callback: function(time) {
			console.log("Ready? Just call me once but call me first! At: " + time);
		},
		/* For equivalent of callback.bind(binding) from Function.prototype.bind */
		binding: null,
		/* Calls `off` to remove this subscription after executing its callback once */
		onlyOnce: true,
		/* Adds this item to the front of the call list instead of the end */
		runFirst: true,
	});
	
	emitter.emit("ready", +(new Date()));
	// Console: "Ready? Just call me once but call me first! At: ______"
	// Console: "Ready! At: ______"
	emitter.emit("ready", +(new Date()));
	// Console: "Ready! At: ______"
	
	phantom.exit();
})(this);

BetterWebPage

BetterWebPage is a CommonJS module that extends the PhantomJS core WebPage module with a slew of features. Its enhancements include:

Add a new method page.getDeferencedObject to help with deferencing objects retrieved from the client-side to avoid peculiar object behavior back in the PhantomJS outer space
Improved page.evaluate:
- Shimmed so that the function signature is equivalent to the PhantomJS 1.6+ implementation (which allows the passing of arguments) even when running in older versions
- Added dereferencing to help avoid peculiar object behavior back in the PhantomJS outer space
Adds an EventEmitter API, e.g.: page.on("init", function() { }); instead of page.onInitialized = function() { }; page.off("init"); instead of page.onInitialized = null;

Events supported: 1. "init" (requires PhantomJS 1.3+) 1. "resource.request" (requires PhantomJS 1.2+) 1. "resource.receive." (requires PhantomJS 1.2+) 1. "resource.receive.start" (requires PhantomJS 1.2+) 1. "resource.receive.finish" (requires PhantomJS 1.2+) 1. "load.start" (requires PhantomJS 1.2+) 1. "load.finish" (requires PhantomJS 1.2+) 1. "open" (requires PhantomJS 1.2+) 1. "navigate.request" (requires PhantomJS 1.6+) 1. "navigate.complete" (requires PhantomJS 1.6+) 1. "close" (requires PhantomJS 1.7+) 1. "callback" (requires PhantomJS 1.6+) 1. "error" (requires PhantomJS 1.5+) 1. "alert" (requires PhantomJS 1.0+) 1. "confirm" (requires PhantomJS 1.6+) 1. "prompt" (requires PhantomJS 1.6+) 1. "console." (requires PhantomJS 1.2+) 1. more coming soon...
The callback passed to page.open(url, callback) will be implicitly attached with page.on("open", callback) (see Special Notes below).

Compatibility:

Minimum: PhantomJS 1.3+

Attachment Target: N/A

Basic Usage:

(function(window) {
	var page = require("BetterWebPage").create();
	
	/* Handlers for "open" will always defer firing until AFTER all the "load.finish" handlers have been executed */
	page.on("open", function() {
		console.log("Check 3? Check check check!");
	});
	page.on("load.finish", function() {
		console.log("Check 1? Check!");
	});
	/* Can have multiple handlers for both the "load.finish" and "open" events */
	page.on("load.finish", function() {
		console.log("Check 2? Check check!");
	});
	page.open("http://google.com/", function(status) {
		/* This whole callback will be implicitly attached with `page.on("open", thisFunctionRef)` */

		console.log("Check 4? Let's rock! \m/");
		phantom.exit();
	});
})(this);

Special Notes:

Regarding "load.finish": This event will fire from your top-level page (the URL passed to page.open) as well as
from all of that page's child pages/frames/iframes. This is standard PhantomJS behavior for the
WebPage#onLoadFinished callback but tends to surprise new users.
Regarding "open":
- This event will be emitted AFTER all registered handlers for "load.finish" have been executed.
- Handlers registered for this event will be executed exactly once and then automatically removed. This means
  that "open" handlers will not be fired for child pages/frames/iframes like the "load.finish" handlers
  will be.
Regarding "confirm": The event will only be confirmed (return true) if EVERY registered handler returns true.
Regarding "prompt": The event will receive its answer/value from the FIRST string value returned by a registered
handler, including empty string (""). If no string values were returned, it will receive null.