Skip to content
Browse files

updated example for readme, and phantom check

  • Loading branch information...
1 parent 27adb0b commit e256e9ce98956aa8540d9f436d45fcb58d05bb5e @jdonaldson committed Sep 20, 2012
Showing with 51 additions and 26 deletions.
  1. +44 −17 Readme.md
  2. +7 −9 src/js/phantomjs/PhantomTools.hx
View
61 Readme.md
@@ -18,51 +18,78 @@ instance will not have the Haxe standard lib by default, such as trace, Hash,
etc. The current method of dealing with this is to include a small js file in
the evaluated page containing the compiled haxe libs.
+## injectThis()
PhantomTools provides "injectThis" which will inject the current script into
-the page, which will provide all of the methods from your phantomjs script
-in the page you are evaluating.
+the page. This will provide all of the methods from your phantomjs script
+in the page you are evaluating.
```javascript
var page = WebPage.create();
PhantomTools.injectThis(page);
+page.evaluate(function(){
+ var h = new Hash<Int>(); // haxe specific methods here.
+ });
```
-The scope, however, will still not be available.
-It is also necessary to prevent the phantomjs script from executing its static
-main function in the evaluated page. You can check the result from
-PhantomTools.inPhantom() to avoid running main() in an evaluated page:
+This is extremely useful, but still has some significant issues and some
+potential for problems.
+
+### Scoping
+
+page.evaluate is executed *within* the constructed page The evaluate callback
+is not a closure, and should be treated as a completely separate method that
+(thanks to injectThis) happens to have access to all of the same library
+methods. You can pass simple objects to the evaluated method; Anything that
+can be serialized via JSON will work.
+
+```javascript
+var page = WebPage.create();
+PhantomTools.injectThis(page);
+var k = 'a variable in the phantom scope';
+page.evaluate(function(){
+ trace(k); // k is undefined: this function is in a separate page scope.
+ });
+```
+
+### Preventing Static Main
+
+Under normal circumstances, injectThis() will insert itself into the page, and
+try to execute its static main. To prevent this from happening, you can
+check the result from PhantomTools.noPhantom() to avoid running main() in an
+evaluated page:
```javascript
static function main(){
- if (!PhantomTools.inPhantom()) return;
+ if (PhantomTools.noPhantom()) return; // evaluated in a page, exit immediately.
//[...]
```
-## Warnings
-### injectThis() and Sandboxing
+### Sandboxing
Keep in mind that PhantomTools.injectThis() loads phantomjs application code
into a sandboxed page instance, which may be running a page with unknown third
party code. Be cautious when using it, since it could potentially leak
passwords, credentials, etc. that are contained in the phantomjs script
source.
-### window.onerror, js.Lib, and PhantomTools.exposeWindowErrors
+### Unhandling errors
Haxe's default js.Lib will automatically set a window.onerror handler that
catches all page errors. This can block error messages from reaching Phantom's
error handlers. One way of preventing this from happening is to use
-js.Lib.setErrorHandler(f); where "f" will always return false. The other way
-is to use PhantomTools.exposeWindowErrors(page) on the relevant Phantom WebPage
-"page". The PhantomTools method works in all cases.
+js.Lib.setErrorHandler(f); where "f" will always return true. The other way is
+to use PhantomTools.exposeWindowErrors(page) on the relevant Phantom WebPage
+"page". The exposeWindowErrors() method will work whether or not you have used
+injectThis().
For instance, here's an example class that shows a typical workflow.
```javascript
// PhantomTest.hx
-import js.Lib; // for sake of illustration, include js.Lib manually.
+import js.Lib;
import js.phantomjs.WebPage;
import js.phantomjs.PhantomTools;
+
class PhantomTest{
static function main(){
if (!PhantomTools.inPhantom()) return; // exit if not in phantom scope
@@ -71,12 +98,12 @@ class PhantomTest{
page.open("some_arbitrary_webpage.html", function(status){
PhantomTools.injectThis(page); // include this script in the opened page
PhantomTools.exposeWindowErrors(page); // "unhandle" the default window errors for the page.
- page.onError = function(x,i) trace("page error: " + x); // handle errors on this page
+ page.onError = function(x,i) trace("page error: " + x); // phantom handles errors on this page
var argument = 'blah blah blah'; // set some text to send to the page
var result = page.evaluate(function(argument){
- var h = new Hash<String>(); // use some Haxe library methods, gained from injectThis.
+ var h = new Hash<String>(); // use any Haxe library method, courtesy of injectThis.
Lib.document.innerHTML = argument; // set the document content with the argument
- untyped h.invalid_method(); // trigger an error
+ untyped h.invalid_method(); // trigger an error, for illustration purposes
}, argument); // pass the text to the page
}
page.render("output.png"); // render the page.
View
16 src/js/phantomjs/PhantomTools.hx
@@ -17,27 +17,25 @@ class PhantomTools {
}
/**
- Sets a window.onerror handler that will always return false (if
+ Sets a window.onerror handler that will always return true (if
appropriate). This will ensure that page errors are captured by Phantom
error handlers.
**/
public static function exposeWindowErrors(page:WebPage):Bool{
return page.evaluate(function(){
- if( untyped __js__("typeof window") != "undefined" ) {
- untyped window.onerror = function() return false;
- }
- return true;
+ if( untyped __js__("typeof window") != "undefined" )
+ untyped window.onerror = function() return true;
+ return true;
});
}
/**
Simple routine which detects if it is running inside of the main Phantom
scope.
**/
- inline public static function inPhantom():Bool{
- if( untyped __js__("typeof window") != "undefined" ) {
- return untyped window.hasOwnProperty('phantom');
- } else return false;
+ inline public static function noPhantom():Bool{
+ if( untyped __js__("typeof window") == "undefined" ) return true; // phantom always has window
+ else return untyped !window.hasOwnProperty('phantom'); // phantom always has window.phantom
}
}

0 comments on commit e256e9c

Please sign in to comment.
Something went wrong with that request. Please try again.