Renderers are objects that load() input for presentation. The Renderer class defines the core API to Renderer instances. Renderer is implemented as an abstract class, in that it does not prescribe several core mechanisms, e.g. how to load and present the provided data.

Public API:

render-vendor ships with a default Renderer. You access it using the public API, exposed as static properties + functions on the Renderer constructor. The public API is also available on every Renderer instance.

See ChromeRenderer & PhantomRenderer for documentation about the options accepted by:

  • Renderer.load(id, options)
  • Page#render(options)

Attributes:

isBooting (get|set)

Type: Boolean

true when booting. Setting this value will automatically set isBooted to false.

isBooted (get|set)

Type: Boolean

true when booted. Setting this value will automatically set isBooting to false.

pages (get)

Type: [Page]

Array of Page instances loaded by the Renderer instance. Can be pushed to + spliced from.

Functions:

All functions tagged as async return Promises. “Return value” indicates what a successful promise will resolve with, either via await or .then(...).

find(id)

Returns: Page|undefined

Finds a Page with the given ID in the Renderer’s pages array

async load(id, options = {})

Returns: Page

Finds or creates a Page with the given ID, then loads it with the passed options. Promise resolves with the Page instance.

async refresh()

Returns: -

Tries to reload Page instances from a previously-booted Renderer. Useful when e.g. recovering access to a parallelized Renderer. Promise resolves with no args, and never rejects.

async destroy()

Returns: -

Iterates over all owned pages to destroy each Page instance, then attempts to shutdown the Renderer instance

async \_exec(command, page, ...args)

Returns: *

Ensures the Renderer instance is booted, then calls and proxies the response for the corresping ${command}Page function. Ideally you will not call to _exec directly; it is used primarily to ensure boot state when Page instances proxy commands to their Renderer instance.

Events

Renderers extend Node.js’ EventEmitter class. Renderer implementations may emit several events, to which can you register callback functions. See EventEmitter docs for more details.

The PhantomRenderer emits two events by default

  • message; and
  • error

Other static attributes

rendererConstructor (get,set)

Type: Constructor|Function|undefined

Set this to a constructor or function to override the default Renderer implementation. On init (+ when re-set to undefined), this returns PhantomRenderer.

renderer (get|set)

Type: Renderer

Set this to override the default Renderer used by the proxying getters + methods. On init (+ when re-set to undefined), this will construct a new Renderer instance by calling this.rendererConstructor().

Constructor:

All calls to new Renderer() accept an attrs object, which is then applied to the returned instance.

:WARNING: BE CAREFUL: While a basic Renderer instance may not be useful, you should trust that any extensions of the class implement at least the following API:

For example:

let renderer = new Renderer();
let rendererWithFoo = new Renderer({ foo: 'FOO?!?' });

console.log(renderer.foo);
// undefined

console.log(rendererWithFoo.foo);
// FOO?!?

Private API:

The following functions throw Renderer.Error.NotImplemented by default, unless overridden by an extension (e.g. PhantomRenderer). These functions are used to affect the renderer’s state, and are wrapped to provide a predictable API.

async boot()

Returns: -

Instructs the Renderer implementation to boot; should set isBooted = true and return once complete.

async shutdown()

Returns: -

Instructs the Renderer implementation to shut down; should set isBooted = false and return once complete.

async ping()

Returns: Object

Requests status info from the Renderer implementation. If pages are recoverable, the returned Object should include an array of page IDs keyed like: { ids: [...] }.

async loadPage(page, ...args)

Returns: -

Instructs the Renderer implementation to load the passed Page instance. Implementation should wait until page is loaded before resolving.

async renderPage(page, ...args)

Returns: *

Instructs the Renderer implementation to render the passed Page instance. Implementation should wait until rendered data is generated, and resolve with either the raw data or a URI pointing to it (can depend on the args provided).

async unloadPage(page, ...args)

Returns: -

Instructs the Renderer implementation to unload the passed Page instance. Implementation should wait until page is unloaded before resolving.