API

• Draw a page to the canvas.

  rasterizeHTML.drawURL( url [, canvas] [, options] )
  

• Draw a HTML string to the canvas.

  rasterizeHTML.drawHTML( html [, canvas] [, options] )
  

• Draw a Document to the canvas.

  rasterizeHTML.drawDocument( document [, canvas] [, options] )
  

###Parameters:

• url a URL, or
• html a string of HTML, or
• document a Document object.

###Optional parameters:

• canvas a HTML5 canvas node
• options key/value pairs of further options
  • width the width of the viewport, by default the width of the canvas, or '300' if not provided.
  • height the height of the viewport, by default the height of the canvas, or '200' if not provided.
  • baseUrl the URL base of the HTML document which relative resources will be based on, default: null.
  • executeJs if set to true, it will execute JavaScript in the page/HTML string and wait for the onload event before drawing the content (not available for drawDocument), default: false.
  • executeJsTimeout will wait the given amount of milliseconds before interrupting the execution of JavaScript. Will also wait if no script is running, default: 0.
  • zoom a factor to zoom the displayed content by, default: 1.
  • hover a selector whose matched element receives a simulated mouse hover to match :hover style rules, default: null. See limitations below
  • active a selector whose matched element receives a simulated user activation to match :active style rules, default: null. See limitations below
  • cache allows fine-tuning caching behaviour:
    • 'none' forces requested pages not to be cached by the browser by adding a unique query string in the form of "?_=[timestamp]" to each request,
    • 'repeated' forces a non-cached load for initial calls and caches repeated calls to the same URL,
    • 'all' will not employ any cache busting (default).
  • cacheBucket an object holding the library's own in-memory cache. Only effective in reuse between several calls to the API. Should be initialized with '{}'.
• callback(image, failedResources) callback function, called when the HTML has been rendered. deprecated, use returned promise (see below)

###Return value:

All methods return a promise that is fulfilled once the content is rendered or rejected if drawing the provided item failed. The general call pattern for any of the methods is

rasterizeHTML.drawURL(url, canvas, options)
    .then(function success(renderResult) {
         ...
    }, function error(e) {
        ...
    });

On success

The renderResult object consists of

• image the resulting image rendered to the canvas. If content overflows the specified viewport (defined by the width and height parameters or the canvas element's size) the image will have greater dimensions.
• errors a list of resources that failed to load. See below.

On error

On error the error handler is executed with the error e of the form {message: "THE_MESSAGE"} with the message being one out of

• "Unable to load page" if the URL passed to drawURL could not be loaded,
• "Error rendering page" general error if the whole document failed to render,
• "Invalid source" if the source has invalid syntax (and more specifically cannot be converted into the intermediate XHTML format needed to render the HTML).

Failed resources

The list of failed resources is returned in the following form: { resourceType: "TYPE_OF_RESOURCE", url: "THE_FAILED_URL", msg: "A_HUMAN_READABLE_MSG" }

Resource types:

• image an <img href=""> or <input type="image" src="">
• stylesheet a <link rel="stylesheet" href=""> or @import url("");
• backgroundImage a background-image: url("");
• fontFace a @font-face { src: url("") }
• script a <script src="">
• scriptExecution a script execution error message (no url specified)
• document a Document object (general error when the whole Document failed to render, no url specified) only in deprecated callback
• page a HTML page (passed to rasterizeHTML.drawURL()) only in deprecated callback

###Limitations

The way rasterizeHTML.js simulates :hover and :active selectors does not allow it to trigger user-agent specific preset stylesheets. This e.g. includes the button outline in Chrome or the padding-left offset in Firefox on active state.

For questions, reach out to @cburgmer on Twitter.