roHtmlWidget
This object embeds the Chromium HTML rendering engine, which can be rendered at full screen or as a widget. You can display multiple roHtmlWidget instances at the same time. The JavaScript equivalent is htmlwidget.
Tip
Use the roKeyStore object to provide client certificates for websites. Use the roVirtualMemory object to set up a virtual memory repository for Chromium.
Object Creation
The roHtmlWidget object is initialized with an roRectangle object, which specifies the size and positioning of the widget on the screen, and an optional associative array, which defines properties for the widget.
CreateObject("roHtmlWidget", rect As roRectangle, properties As roAssociativeArray)
The properties of an roHtmlWidget instance can be set with an associative array at initialization or with equivalent methods after initialization. Because many roHtmlWidget properties cannot be changed without reloading the page (and can produce unpredictable results if changed while the page is running), we recommend setting properties at initialization when possible, rather than using the equivalent methods.
Important
Defining initialization properties for an roHtmlWidget instance disables some methods for that instance (e.g. SetTransform()
, AddFont()
, SetUserStylesheet()
). See the “Available Methods with Initialization” section below for a list of available methods.
Initialization Parameters
The associative array passed during initialization can have the following parameters:
nodejs_enabled
bool: Enables Node.js® on the widget. This value is false
by default.
Reloading a page which has Node.js enabled can be classified as an undefined behavior. The recommended method for restarting a Node instance is to destroy and rebuild the roHtmlWidget
focus_enabled
bool: Enables focus for mouse/touchscreen events. This value is true
by default.
mouse_enabled
bool: Enables mouse/touchscreen events. This value is false
by default.
scrollbar_enabled
bool: Enables automatic scrollbars for content that does not fit into the viewport. This value is false
by default.
The browser defaults to desktop-style scrollbars, but they can be configured for mobile style as well.
pinch_to_zoom_enabled
bool: Enables pinch-to-zoom functionality. This value is false
by default.
force_gpu_rasterization_enabled
bool: Enables GPU rasterization for HTML graphics. By default, the decision to use GPU rasterization is based on internal Chromium logic.
canvas_2d_acceleration_enabled
bool: Enables 2D canvas acceleration. This will improve the framerate of most HTML pages that use 2D animations, but can cause out-of-memory issues with pages that use a large number of off-screen canvas surfaces.
javascript_enabled
bool: Enables JavaScript on the widget. This value is true
by default.
brightsign_js_objects_enabled
bool: Enables BrightScript-JavaScript objects. This value is false
by default.
In OS 8.2.55.4 and later, html widgets that are loaded from HTTP/HTTPS protocols do not share the same local storage database (html widgets that are loaded via file protocol act as they did in previous releases). These flags allow you to change the default behavior of widgets loaded through HTTP/HTTPS from "unshared" to "shared", or to change the default behavior of widgets with locally loaded files to "unshared" from "shared":
force_shared_storage
bool: Allows HTML widgets loaded via HTTP/HTTPS protocol to share local storage if they are loaded from the same domain.
force_unshared_storage
bool: Prevents HTML widgets loaded via FILE protocol from sharing storage.
transform
string: Sets the screen orientation of content in the widget (note that the coordinates and dimensions of the roRectangle containing the widget are not affected by rotation). The following values are accepted:
"identity"
: There is no transform (i.e. the widget content is oriented as landscape). This is the default setting."rot90"
: The widget content is rotated to portrait at 90 degrees (clockwise)."rot180"
: The widget content is rotated to portrait at 180 degrees (clockwise)."rot270"
: The widget content is rotated to portrait at 270 degrees (clockwise).
user_agent
string: Modifies the default user-agent string for the roHtmlWidget instance.
url
string: The URL to use for display. See the SetUrl() entry below for more information on using URIs to access files from local storage.
language
string: Specifies the language to load the web page in.
user_stylesheet
string: Applies the specified user stylesheet to pages in the widget. The parameter is a URI specifying any file:
resource in the storage, unless you are using a CSS stylesheet saved to the SD card, in which case you should use sd:/path/filename.css
. The stylesheet can also be specified as inline data.
hwz_default
string: Specifies the default HWZ behavior. This value is off
by default. To enable it, set it to on
.
storage_path
string: Creates a "Local Storage" subfolder in the specified directory. This folder is used by local storage applications such as the JavaScript storage class.
storage_quota
string or double: Sets the total size (in bytes) allotted to all local storage applications (including IndexedDB). A BrightScript integer is only guaranteed to be able to represent a count of bytes up to 2GB so avoid using integers when calculating the size: Use float or double instead since they can represent values over 2GB (string can also be used but is not recommended). If the storage path is specified without a storage quota, Chromium defaults to reserving 1GB plus 10% of the total size of the storage device.
port
roMessagePort: Configures the message port to which the roHtmlWidget instance will send events. When using initialization parameters, the port
parameter should be used instead of the SetPort()
method to ensure the script can catch load-started
, load-finished
, and load-error
events.
fonts
roArray: Specifies a list of font files that can be accessed by the webpage. Font files are specified as an array of string filenames. Supported font types include TrueType Font files (.ttf) and Web Open Font files (.woff, .woff2).
pcm_audio_outputs
roArray: Configures the PCM audio output for the HTML widget. Outputs are specified as an array of strings, each string being the name of an output. (See roAudioOutput documentation for a list of acceptable names.)
compressed_audio_outputs
roArray: Configures compressed audio output (e.g. Dolby AC3 encoded audio) for the HTML widget. Outputs are specified as an array of roAudioOutput instances.
multi_channel_audio_outputs
roArray: Configures multi-channel audio output for the HTML widget. Outputs are specified as an array of roAudioOutput instances.
inspector_server
roAssociativeArray: Configures the Chromium Inspector for the widget.Starting in BrightSign OS 8.5.31 you will need to also set the enable_web_inspector registry key (in the "html" section) to enable the JavaScript console. In “enable_web_inspector”, "1" will allow the inspector and "0" or not present will disable it. A reboot will be needed for these changes to take effect (if you enable/disable this through the LDWS UI it may trigger a reboot to apply the changes).
ip_addr
string: The Inspector IP address. This value is useful if the player is assigned more than one IP address (i.e. there are multiple network interfaces) and you wish to limit the Inspector server to one. The default value is"0.0.0.0"
, which allows the Inspector to accept connections using either IP address.port
int: The port for the Inspector server
security_params
roAssociativeArray: Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc.
websecurity
bool: Enables Chromium security checks for cross-origin requests.camera_enabled
bool: Enables webpage access to USB cameras connected to the player (access is disabled by default). This allows support for WebRTC applications.insecure_https_enabled
bool: Instructs the widget to ignore security errors when connecting to insecure HTTPS hosts (insecure HTTPS is disabled by default). Enabling this feature makes the player insecure; it is not suitable for production environments and should only be used for testing.]audio_capture_enabled
bool: Gives access to audio input devices and lets Chromium enumerate all audio input and output devices
With BOS 8.2 and later (Chromium69 and later), several new CORS checks have been added: security_params.websecurity
or enableSecurity(false)
do not disable all these checks. Use the following registry setting instead:
registry write html disable-web-security 1
To write this to the registry using roRegistrySection:
RegHtml = CreateObject("roRegistrySection", "html")
RegHtml.Write("disable-web-security", "1")
RegHtml.Flush()
This flag will take effect on all roHtmlWidget
instances, as opposed to previous flags which are only effective on the instance they are called on.
javascript_injection
roAssociativeArray: Specifies JavaScript code to inject at different initialization points (JavaScript code can also be injected during runtime using the InjectJavaScript()
method). The associative array can contain three parameters (described below). Each parameter value is an array of associative arrays, each containing a single key/value pair. The array must contain a source
key. The source
value is a string that can contain any of the following: pure JavaScript code, a path to a JavaScript file, or a base64-encoded string (i.e. beginning with data:text/javascript;charset=utf-8;base64,
). Mutliple source
keys can be included, but the load order will be unpredictable. The array can also contain the optional world
key, which can be assigned one of the following values: "application"
, "user"
, or "main"
(see this page for more details); if the world
parameter is not included in the array, "application"
is selected by default.
document_creation
: The script will run as soon as the document is created. This behavior is not suitable for any DOM operation.document_ready
: The script will run as soon as the DOM is ready. This behavior is equivalent to theDOMContentLoaded
event firing in JavaScript.deferred
: The script will run when the page load finishes.
config = {
javascript_injection: {
document_creation: [{source: "0.js" }],
document_ready: [{source: "1a.js" }, {source: "1b.js" }],
deferred: [{source: "2.js" }]
},
url: "..."
}
assets
roArray: Allows the roHtmlWidget instance to access one or more asset pools. If a file exists in multiple specified asset pools, the asset pool with the lowest index in the array has precedence. Each array entry is an associative array containing information about an asset pool:
pool
roAssetPool: An asset pool containing filescollection