VCS WebFrame component
Renders an embedded web page. Similar to
<iframe> element in HTML, but with the following essential differences:
- You can only use one WebFrame element inside a VCS composition. (In other words, WebFrame is a "singleton".)
- Creating multiple WebFrame elements is undefined behavior. They will render the same content even if you set different source URLs. To avoid this, use only one WebFrame element in your composition.
- The WebFrame element doesn't update at a guaranteed frame rate. You should assume the content will be refreshed about two times per second (2 fps).
- You can control the web page by sending keyboard events to it (see section below).
In practice, WebFrame behaves a lot like an image component that renders a live web page instead of a static image asset. You can use all the props that exist on
src prop sets the URL of the web page to be loaded. Note that VCS will load this URL on Daily's cloud-based media servers, so the page must be publicly accessible.
viewportSize prop sets the size of the embedded browser window in pixels. The value must be an object containing properties
h. You should always set this prop to a value that fits your content. If unset, WebFrame will use a default viewport size. The default size is currently 1280*720 pixels, but could change depending on rendering environment.
Properties specific to the
|A URL to be loaded into the embedded web browser.|
|The size of the viewport for the embedded web browser. See description above.|
|A simulated key press to be sent to the embedded web browser. See description above.|
Properties shared with the
|Determines how the browser image should be rendered within its layout frame. Available values: |
|An object defining transformations to be applied at the compositing stage. Supported properties: |
|An object of compositing-related properties. Supported child properties: |
Properties available to all VCS components, including this one.
|A name of your choice for the component instance. Works just like the “id” property in HTML. Primarily useful for debugging.|
|This prop has a special meaning to the React runtime. When you render components inside an array (e.g. a list), each individual item in the array should have a different value for the key prop. React uses this internally to quickly compare the rendered array with its previous version.|
|An object of style. Each component class has its own supported style properties. For example, the |
|Allows you to hook into your rendered components into the VCS layout system. After the React render cycle completes, the layout system computes final layout frames (coordinates within the output viewport). You can guide the layout process using callback functions and data you provide using the layout prop. The first value of the array must be a layout function. The second (optional) value can be a data object containing param values, which is passed to the layout function when computing the layout. See Layout API for more details.|
style prop accepts an object that can have the following values set:
|Apply a rounded mask to the corners of the component.|
Sending events to the web page
You can interact with the page loaded into a WebFrame by sending it a key press action, a simulated keyboard event.
This is particularly useful for document viewers. For example, if you're embedding a Google Slides presentation, you might want to first send a key press to enter slideshow mode, then send arrow keys to navigate between slides.
The key press action is described using a prop called
keyPressAction, which is available on the WebFrame component. Its value must be an object with the following properties:
name- the name of the key to be pressed. (See below for list of key names.)
modifiers- a list of modifier keys to be activated for the key press.
- Possible values are:
- On a Mac keyboard,
"Alt"is equal to Option and
"Meta"is equal to Command.
- You should combine the keys with a plus sign. E.g.
- Possible values are:
key- a unique identifier for this specific key press.
- Should be an integer greater than zero.
key property is required because a key press is functionally an event occurring at a specific moment in time (the simulated key is pressed and depressed). Because the same keys can be pressed over and over, we need a way to tell VCS when a key press has just happened. The
key property accomplishes this. When you update
key to a new value, VCS will send the simulated event to the embedded browser.
The following key names are supported:
- Digits 0 - 9
- Letters A - Z
- ASCII special characters, e.g. !, @, +, >, etc.
- Function keys F1 - F12
- Arrow keys ArrowUp, ArrowDown, ArrowLeft, ArrowRight
- PageDown, PageUp
You can combine these with the modifiers listed previously.
The following example functions create key press actions to control a Google Slides document.
Note that the returned object from these functions would be used as the
keyPressAction prop value for a WebFrame component. (In a real application, you'd probably want to store
kpkey in a React ref within the component that contains the WebFrame.)