Page tree
Skip to end of metadata
Go to start of metadata

ON THIS PAGE


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.

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 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 all property methods for that instance (e.g. SetTransform(), AddFont(), SetUserStylesheet()). Other methods that do not affect properties (e.g. Show(), FlushCachedResources()) can still be used.

Initialization Parameters

The associative array passed during initialization can have the following parameters: 

[boolean] nodejs_enabled

Enables Node.js on the widget. This value is false by default.

[boolean] focus_enabled

Enables focus for mouse/touchscreen events. This value is true by default.

[boolean] mouse_enabled

Enables mouse/touchscreen events. This value is false by default.

[boolean] scrollbar_enabled

Enables automatic scrollbars for content that does not fit into the viewport. This value is false by default.

[boolean] force_gpu_rasterization_enabled

Note

This setting has been deprecated. As of firmware 7.2, GPU rasterization will always be enabled, so setting this flag to true will have no effect.

Enables GPU rasterization for HTML graphics. By default, the decision to use GPU rasterization is based on internal Chromium logic. Setting this value to true/false will enable/disable it for all content.

[boolean] canvas_2d_acceleration_enabled

Note

This setting has been deprecated. As of firmware 7.2, Canvas acceleration will always enabled, so setting this flag to true will have no effect.

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. This value is true by default in firmware versions 7.0.x and later and false by default in firmware versions 6.2.x and earlier.

[boolean] javascript_enabled

Enables JavaScript on the widget. This value is true by default.

[boolean] brightsign_js_objects_enabled

Enables BrightScript-JavaScript objects. This value is false by default.

[string] transform

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).
  • "rot270": The widget content is rotated to portrait at 270 degrees (counter-clockwise).
[string] user_agent

Modifies the default user-agent string for the roHtmlWidget instance.

[string] url

The URL to use for display. See the SetUrl() entry below for more information on using URIs to access files from local storage.

[string] user_stylesheet

Applies the specified user stylesheet to pages in the widget. The parameter is a URI specifying any file: resource in the storage. The stylesheet can also be specified as inline data.

[string] hwz_default

Specifies the default HWZ behavior. See the SetHWZDefault() entry below for more information.

[string] storage_path

Creates a "Local Storage" subfolder in the specified directory. This folder is used by local storage applications such as the JavaScript storage class. 

[string or double] storage_quota

Sets the total size (in bytes) allotted to all local storage applications (including IndexedDB). A number literal can only represent byte numbers up to 2GB; use a string to specify larger amounts. The default total size is 10GB (or 1GB less than the total size of the storage device, whichever is less).

[roMessagePort] port

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-startedload-finished, and load-error events.

[roArray] fonts

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

[roArray] pcm_audio_outputs

Configures the PCM audio output for the HTML widget. Outputs are specified as an array of roAudioOutput instances.

[roArray] compressed_audio_outputs

Configures compressed audio output (e.g. Dolby AC3 encoded audio) for the HTML widget. Outputs are specified as an array of roAudioOutput instances. 

[roArray] multi_channel_audio_outputs

Configures multi-channel audio output for the HTML widget. Outputs are specified as an array of roAudioOutput instances.

[roAssociativeArray] inspector_server

Configures the Chromium Inspector for the widget.

  • [string] ip_addr: 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.

  • [int] port: The port for the Inspector server.

[roAssociativeArray] security_params

Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc. 

  • [Boolean] websecurity: Enables Chromium security checks. 
  • [Boolean] camera_enabled: Enables webpage access to USB cameras connected to the player (access is disabled by default). This allows support for WebRTC applications.
  • [Boolean] insecure_https_enabled: Instructs the widget to ignore security errors when connecting to insecure HTTPS hosts (insecure HTTPS is desabled by default). Enabling this feature makes the player insecure; it is not suitable for production environments and should only be used for testing.

Note

The camera_enabled parameter is currently supported on the XTx44, XTx43, 4Kx42, XDx34, XDx33, HDx23, and LS423 models.

[roAssociativeArray] javascript_injection

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 equivelant to the DOMContentLoaded event firing in JavaScript. 
  • deferred: The script will run when the page load finishes. The DOM cannot be changed at this point.

config = {
      javascript_injection: { 
         document_creation: [{source: "0.js" }], 
         document_ready: [{source: "1a.js" }, {source: "1b.js" }], 
         deferred: [{source: "2.js" }] 
      },
      url: "..."
   }
[roArray] assets

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:

  • [roAssetPool] pool: An asset pool containing files 
  • [roAssetCollection] collection: A manifest identifying the files in the pool
  • [string] uri_prefix: The URI prefix of the webpage resources to retrieve from the pool
  • [string] pool_prefix: The pool prefix that will replace the URI prefix when looking up the resource in the pool

ifHtmlWidget

GetFailureReason() As String

Gives more information when a member function returns false.

Hide() As Boolean

Hides the widget.

Show() As Boolean

Shows the widget.

SetRectangle(r As roRectangle) As Boolean

Changes the size and positioning of the widget rectangle using the passed roRectangle object.

SetURL(URL As String) As Boolean 

Displays content from the specified URL. When using this method to retrieve content from local storage, specify the file location as follows: "file:/<drive>:/<directory>/<filename>". For example, an index.html file in the "Content" folder on the SD card can be selected with the string "file:/SD:/Content/index.html". You can also omit the drive specification to select the currently active drive (i.e. whichever drive the current autorun as loaded from).

MapFilesFromAssetPool(asset_pool As roAssetPool, asset_collection As roAssetCollection, pool_prefix As String, uri_prefix As String) As Boolean 

Sets the mapping between the URL space and the pool files. HTML content that has been deployed via BrightAuthor will typically reside in the pool and have encrypted SHA1-based filenames. A mapping mechanism is required to allow any relative URIs contained in the HTML content to continue working and to locate the appropriate resources in their respective pool locations.

You can use this method to bind part of the resource URI space onto pool locations. This method accepts the following arguments: an roAssetPool object containing assets, an roAssetCollection object identifying the assets, and two semi-arbitrary strings (URI_PREFIX and POOL_PREFIX).

Any URI in the form "file:/[URI_PREFIX][RESOURCE_ID]" will be rewritten into the form "[POOL_PREFIX][RESOURCE_ID]". It will then be located in the pool as if that name had been passed to the roAssetPoolFiles.GetPoolFilePath() method. This binding occurs for every instance of roHtmlWidget, so different mappings can be used for different bundles of content.

SetZoomLevel(scale_factor as Float) As Boolean

Adjusts the scale factor for the displayed page (the default equals 1.0).

EnableSecurity(enable As Dynamic) As Boolean 

Enables or disables Chromium security checks for cross-origin requests, local video playback from HTTP, etc. (if the argument is Boolean). This method can also accept an associative array, which can contain the following parameters:

  • [Boolean] websecurity: Enables Chromium security checks. This parameter is identical to passing a Boolean argument to the method itself.
  • [Boolean] camera_enabled: Enables webpage access to USB cameras connected to the player (access is disabled by default). This allows support for WebRTC applications.
  • [Boolean] insecure_https_enabled: Instructs the widget to ignore security errors when connecting to insecure HTTPS hosts (insecure HTTPS is desabled by default). Enabling this feature makes the player insecure; it is not suitable for production environments and should only be used for testing.

Note

The camera_enabled parameter is currently supported on the XTx44, XTx43, 4Kx42, XDx34, XDx33, HDx23, and LS423 models.

EnableMouseEvents(enable As Boolean) As Boolean

Enables response to mouse/touchscreen presses if true. Setting this method to false (the default) disables this feature.

SetPortrait(portrait_mode As Boolean) As Boolean

Sets the widget orientation to portrait if true. If this method is false (the default), the widget is oriented as a landscape.

Important

 The SetPortrait() method has been deprecated in firmware 6.1. We recommend using the SetTransform() method instead.

SetTransform(transform As String) As Boolean

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). This method accepts the following strings:

  • "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).
  • "rot270": The widget content is rotated to portrait at 270 degrees (counter-clockwise).
SetAlpha(alpha As Integer) As Boolean

Sets the overall alpha level for the widget (the default equals 255).

EnableScrollbars(scrollbars As Boolean) As Boolean

Enables automatic scrollbars for content that does not fit into the viewport if true. Setting this method to false (the default) disables this feature.

AddFont(filename As String) As Boolean

Supplies additional or custom typefaces for the HTML rendering engine. Supported font types include TrueType Font files (.ttf) and Web Open Font files (.woff.woff2). 

SetPcmAudioOutputs(outputs As roArray) As Boolean

Configures the PCM audio output for the HTML widget. This method accepts one or more outputs in the form of an roArray of roAudioOutput instances.

SetCompressedAudioOutputs(outputs As roArray) As Boolean

Configures compressed audio output (e.g. Dolby AC3 encoded audio) for the HTML widget. This method accepts one or more outputs in the form of an roArray of roAudioOutput instances. 

Note

When one or more audio-output methods are called, they will override the settings of the following ifAudioControl methods: SetAudioOutput(), MapStereoOutput(), SetUsbAudioPort(), MapDigitalOutput(). Calls to HTML audio-output methods will only take effect with subsequent calls to SetUrl(). Audio-output settings on an roHtmlWidget instance will be overwritten by equivalent settings in the HTML.

SetMultichannelAudioOutputs(outputs As roArray) As Boolean
 
SetHWZDefault(default As String) As Void 

Sets the default HWZ mode for HTML video. Normally, HWZ must be enabled in each <video> tag, but passing "on" to this string enables HWZ for all <video> elements. This method can also accept a semicolon-separated list of HWZ parameters:

  • on/off: Enables or disables HWZ mode.
  • z-index: Sets the default z-ordering for <video> elements. A positive integer places the video in front of all graphics; a negative integer places the video behind all graphics; and a zero value disables HWZ mode completely. You can customize the z-ordering of individual video elements with respect to each other by inserting the "z-index" parameter into the <video> tag.
  • transform: Sets the default rotation for <video> elements. HWZ mode must be enabled for transforms to work.
    • identity: No transformation (default behavior)
    • rot90: 90 degree clockwise rotation
    • rot180: 180 degree rotation
    • rot270: 270 degree clockwise rotation
    • mirror: Horizontal mirror transformation
    • mirror_rot90: Mirrored 90 degree clockwise rotation
    • mirror_rot180: Mirrored 180 degree clockwise rotation
    • mirror_rot270: Mirrored 270 degree clockwise rotation
  • fade: Sets the fading behavior for <video> elements.
    • auto: Videos transition without fade effects. This is the default behavior.
    • always : When a video ends, the video window will go black. The new video will then fade in.
  • luma-key/cr-key/cb-key: Enables luma and/or chroma keying for <video> elements. HWZ mode must be enabled for luma/chroma keying to work.
Example
 html.SetHWZDefault("on; transform:rot90; luma-key:#ff0020;")
SetVideoPlayerDefaults(defaults As roAssociativeArray) As Boolean

Sets default playback settings for <video> elements in the widget. Available parameters are identical to the roVideoPlayer.PlayFile() method. Default settings will be overwritten by parameters specified in individual <video> elements.

ForceGpuRasterization(enable As Boolean) As Boolean

Enables GPU rasterization for HTML graphics. This method will take effect for subsequent page loads only. If Chromium determines that a page is not compatible, it will refuse to enable GPU rasterization for that page.

Note

This method has been deprecated. As of firmware 7.2, GPU rasterization will always be enabled, so calling this method will have no effect.

EnableCanvas2dAcceleration(enable As Boolean) As Boolean

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. We recommend thoroughly testing this method with your HTML content before deploying it.

Note

This method has been deprecated. As of firmware 7.2, Canvas acceleration will always be enabled, so calling this method will have no effect.

SetUserStylesheet(URI As String) As Boolean 

Applies the specified user stylesheet to the page(s) loaded in the widget. The parameter is a URI specifying any file: resource in the storage. The stylesheet can also be specified as inline data in the following form:

"data:text/css;charset=utf-8;base64,<base64 encoded data>"

This method will fail if you specify the inline data in any other order or if you use any data format other than base64.

SetAppCacheDir(file_path As String) As Boolean

Sets the directory to use for storing the application cache (which services <html manifest="example.appcache"> tags). The file path is passed to the method as a string (e.g. "SD:/appcache").

SetAppCacheSize(maximum As Integer) As Boolean

Sets the maximum size (in bytes) for the application cache. Changing the storage size of the application cache will clear the cache and rebuild the cache storage. Depending on database-specific attributes, you will only be able to set the size in units that are equal to the page size of the database, which is established at creation. These storage units will occur only in the following increments: 512, 1024, 2048, 4096, 8192, 16384, 32768.

FlushCachedResources() As Boolean

Discards any resources that Chromium has cached in memory.

SetLocalStorageDir(file_path As String) As Boolean

Creates a "Local Storage" subfolder in the specified directory. This folder is used by local storage applications such as the JavaScript storage class.

SetLocalStorageQuota(maximum As Dynamic) As Boolean

Sets the total size (in bytes) allotted to all local storage applications. This method can accept a string, double, or integer. A number literal can only represent byte numbers up to 2GB; use a string to specify larger amounts. The default total size is 10GB (or 1GB less than the total size of the storage device, whichever is less).

SetWebDatabaseDir(file_path As String) As Boolean

Specifies the directory that should be used for web database applications (e.g. "SD:/webdb"). This method must be called before using web database applications such as Web SQL or IndexedDB.

SetWebDatabaseQuota(maximum As Dynamic) As Boolean

Sets the total size (in bytes) allotted to all web database applications. This method can accept a string, double, or integer. A number literal can only represent byte numbers up to 2GB; use a string to specify larger amounts. The default total size is 5MB.

EnableJavaScript(enable As Boolean) As Boolean

Enables/disables JavaScript on the widget. JavaScript is enabled by default.

AllowJavaScriptURLs(url_collection As roAssociativeArray)

Allows the specified JavaScript BrightScript classes to be used by the specified URLs (all BrightScript classes in JavaScript are disabled by default). This method accepts an associative array that maps JavaScript BrightScript classes to the URL(s) that are allowed to use them.

  • An all key indicates that all classes are authorized for the associated URL(s).
  • An asterisk "*" value indicates that all URLs are authorized for the associated BrightScript class.
  • A "local" value indicates that all local pages are authorized for the associated BrightScript class.

The following will enable all BrightScript classes for all URLs:

html.AllowJavaScriptUrls({ all: "*" })

The following will enable all BrightScript classes for local pages and the BrightSign homepage:

html.AllowJavaScriptUrls({ all: ["local", "http://www.brightsign.biz"]})
PostJSMessage(data As roAssociativeArray) As Boolean

Posts a collection of key:value pairs to the BSMessagePort JavaScript class (see the JavaScript Objects for BrightScript tech note for more details). This method does not support passing nested associative arrays.

InjectJavaScript(code As String) As Boolean

Immediately injects a user script into the JavaScript engine. The passed string 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, ). 

This method can be used to simulate the bind_ready option:

if type(event) = "roHtmlWidgetEvent" then               
   if event.GetData().reason = "load-finished" then
      h.InsertJavascript("fillPasswordFields()")      
  end if
end if

Note

 Changing the DOM is only possible at bind_dom_loaded and bind_ready. Also, since JavaScript is only guaranteed to be ready at bind_ready, your callbacks must use this event if they invoke any global functions.


StartInspectorServer(port As Integer) As Boolean

Enables the Chromium Inspector, which allows you to debug JavaScript applications while a webpage is running. To access the console, navigate to the player IP address at the specified port number. See this page for documentation relating to the JavaScript console.

SetUserAgent(user_agent As String) As Boolean

Changes the default user-agent string for the roHtmlWidget instance.

GetUserAgent() As String

Returns the currently active user-agent string for the roHtmlWidget instance.

SetUserAgentSuffix(suffix As String) As Boolean

Appends text to the current user-agent string. Subsequent calls to this method will replace the suffix that was previously specified.

SetProxy(proxy as String) As Boolean

Sets the name or address of the proxy server that the roHtmlWidget instance will use to make HTTP requests. This method takes effect immediately. It does not affect network operations performed by other components in the firmware. The string can be used to specify either the proxy URL or the location of a .pac proxy file:

  • Proxy URL: The proxy address should be formatted as "http://user:password@hostname:port". The hostname can contain up to four "*" characters; each "*" character can be used to replace one octet from the current IP address. For example, if the IP address is currently 192.168.1.2, and the proxy is set to "proxy-*-*", then the player will attempt to use a proxy named "proxy-192.168".
  • Proxy File: The .pac proxy file can be located on either the local file system or the network. If the file is local, there are no file-name restrictions; if the file is located on the network, the file name should have a .pac extension. If the URL is a hostname only, it will be considered a proxy-server address rather than a file URL.

Example

 The following are examples of valid location formats for .pac files:

  • file:///storage/sd/asset_pool/a/b/ababababababa
  • http://example:8080/setup/proxy.pac
  • https://example/encrypted/proxy.pac
  • https://example:433/encrypted/proxy.pac
  • ftp://example/files/proxy.pac
  • file:///storage/sd/myproxypac.txt
SetProxyBypass(hostnames As String) As Boolean

Exempts the specified hosts from the proxy configuration on the roHtmlWidget instance. The passed array should consist of one or more hostnames. The player will attempt to reach the specified hosts directly rather than using the proxy that has been specified with the SetProxy() method. For example, the hostname "example.com" would exempt "example.com", "example.com:80", and "www.example.com" from the proxy setting.

ifMessagePort

SetPort(port As roMessagePort)

Posts messages of type roHtmlWidgetEvent to the attached message port.

ifUserData

SetUserData(user_data As Object)

Sets the user data that will be returned when events are raised.

GetUserData() As Object

Returns the user data that has previously been set via SetUserData(). It will return Invalid if no data has been set.

 


 

The following examples show how to configure an roHtmlWidget instance using an associative array or methods. Note that these techniques are mutually exclusive.

Example (with initialization properties)
x = 0
y = 0
width = 1920
height = 1080
url = "http://www.brightsign.biz"
 
rect = CreateObject("roRectangle", x, y, width, height)
 
config = {
url: url,
mouse_enabled: true,
storage_path: "/local/",
}
 
html = CreateObject("roHtmlWidget", rect, config)
 
html.Show()
Example (with methods)
x = 0
y = 0
width = 1920
height = 1080
url = "http://www.brightsign.biz"

rect = CreateObject("roRectangle", x, y, width, height)
html = CreateObject("roHtmlWidget", rect)


html.SetUrl(url)
html.EnableMouseEvents(true)
html.SetLocalStorageDir("/local/")
html.Show()
  • No labels