API

This document describes version 1.2.0.

• 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 (see limitations for zooming).
  • hover a selector whose matched element receives a simulated mouse hover to match :hover style rules, default: null (see limitations for pseudo-class styles).
  • active a selector whose matched element receives a simulated user activation to match :active style rules, default: null (see limitations for pseudo-class styles).
  • focus a selector whose matched element receives a simulated focus to match :focus style rules, default: null (see limitations for pseudo-class styles).
  • target a selector whose matched element receives a simulated target activation to match :target style rules, default: null (see limitations for pseudo-class styles).
  • 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, while allowing the browser to cache 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 and cache set to some value other than none. Should be initialized with {}.

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.
• svg The internal SVG representation of the rendered content.
• 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", originalError: obj} with the message being (amongst others):

• "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).

The optional field originalError provides the underlying error, with more details.

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)

Limitations

See limitations for general limitations and those on a per user-agent basis.

For questions, reach out to @cburgmer on Twitter.